Claude Code(2026)

基础概念

安装与运行

如果使用第三方 API，需要在终端配置好 API 环境变量后，在 IDE 或者终端中开启 claude。

如果使用 claude 订阅，终端使用 /login 登录账号

终端运行：claude，使用 /resume 可以继续某个 session。

---

基础 CLI

Command	What it does	Example
claude	Start interactive mode	claude
claude "task"	Run a one-time task	claude "fix the build error"
claude -p "query"	Run one-off query, then exit	claude -p "explain this function"
claude -c	Continue most recent conversation in current directory	claude -c
claude -r	Resume a previous conversation	claude -r
/clear	Clear conversation history	/clear
/help	Show available commands	/help
exit or Ctrl+D	Exit Claude Code	exit

---

拓展工具

参考文档：官方 extend claude code。官方提到的 Extensions 包括：

• CLAUDE.md

• Skills

• MCP

• Subagents

• Agent teams - 用于多 sessions 整合任务

• Hooks

• Plugins and marketplaces package - plugin 是 skill, hooks, subagents, MCP servers 的结合，比较推荐的有 code intelligence plugin 。

• 查看所有 claude 支持的 tool：链接

下表展示了各个 feature 加入 context 的情况。

Feature	When it loads	What loads	Context cost
CLAUDE.md	Session start	Full content	Every request
Skills	Session start + when used	Descriptions at start, full content when used	Low (descriptions every request)*
MCP servers	Session start	Tool names; full schemas on demand	Low until a tool is used
Code intelligence	After file edits and on demand	Diagnostics after edits; symbol locations on lookup	Low; reduces file reads elsewhere
Subagents	When spawned	Fresh context with specified skills	Isolated from main session
Hooks	On trigger	Nothing (runs externally)	Zero, unless hook returns additional context

---

session 和 branch

• session 之间有独立的 context，claude 可以通过 auto memory 或者 CLAUDE.md 在不同 session 间学习。
• claude --resume 可以在新终端继续某个 session。
• session 是和文件夹绑定的，一个 session 只能绑定一个启动时所在的文件夹。

---

context

• Claude Code 会在接近上下文长度限制时自动管理上下文。它会先清理较早的工具输出，然后在需要时总结对话内容。
• 要控制压缩时保留哪些内容，可以在 CLAUDE.md 中添加一个 Compact Instructions 部分，或者运行带有重点说明的 /compact，例如 /compact focus on the API changes。
• 运行 /context 可以查看哪些内容正在占用上下文空间。
• 运行 /mcp 可以查看每个服务器的成本。
• Subagents 拥有自己全新的上下文，和你的主对话完全分离。它们的工作不会占用或膨胀你的主上下文。完成任务后，它们会返回一个总结。这种隔离机制就是 subagents 有助于长会话的原因。
• Skills 会按需加载。Claude 在 session 开始时会看到 skill 的描述，但完整内容只有在某个 skill 被使用时才会加载。

---

小工具

• 用 Shift+Tab 切换 claude 模式，如 Plan mode , Auto mode , Auto-accept edits , Default
• Claude Code 可以教你如何使用它；你可以问类似 how do I set up hooks? 或 what’s the best way to structure my CLAUDE.md? 这样的问题，Claude 会进行解释；内置命令也会引导你完成设置：/init 会引导你为项目创建 CLAUDE.md，/agents 会帮助你配置自定义 subagents，/doctor 会诊断安装中的常见问题。
• esc 可以马上终端 Claude；
• Claude 正在执行某个操作时，你可以直接打字补充说明，按 Enter 发出去。 这不会立刻停止 Claude 当前正在做的事情 ，但 Claude 会在当前 action 完成后读取你的补充，然后在下一步之前调整计划
• 给 claude 一些可以检查自己工作的东西。
• Explore before implementing
• 边界要具体，过程不要过度规定：委派任务，而不是事无巨细地指挥；但任务也不能太泛化。

官网有推荐的插件：https://claude.com/plugins#plugins

---

CLAUDE.md 和 memories

CLAUDE.md 会在每次 session 开始时加载进上下文，所以要写得 简短、具体、结构清晰 。最好控制在 200 行以内 ，因为太长会占用上下文，也会降低 Claude 遵守指令的稳定性。

项目里有 AGENT.md 时，可以直接把 claude.md 设置成软连接。

指令应该用 markdown 标题和 bullet 分类，并写成可验证的具体规则

CLAUDE.local.md：给某一层目录添加你个人的、本地的、不要提交到 Git 的 Claude 指令。

如果规则只适用于某些目录或文件类型，应该放到 path-scoped rules，而不是全部塞进 CLAUDE.md，如：

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

rules 可以在头部加入 paths 来声明应用的文件范围：

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

可以在用户文件夹下添加用户专属 rule：

~/.claude/rules/
├── preferences.md    # Your personal coding preferences
└── workflows.md      # Your preferred workflows

如果 CLAUDE 没有遵从特定的指令，可以参考这里的修正指南。

样例：

Welcome to the real-time AI voice agent platform repository. This file contains the main points for new contributors.

## Project overview

This project is a real-time AI voice agent platform. Users join a LiveKit room through the web frontend and speak with an AI agent. The system runs with Docker Compose and includes three application services alongside a self-hosted LiveKit server.

## Repository overview

*  **Frontend** : `apps/frontend/` contains the browser UI. It uses Next.js 15, TypeScript, and pnpm. 
*  **Agent** : `apps/agent/` contains the AI worker. It uses Python 3.11, uv, and `livekit-agents`. 
*  **Server** : `apps/server/` contains the token server. It uses Python 3.11, uv, and FastAPI. 
*  **LiveKit server** : self-host livekit server.

## Local workflow

Always check out a new branch `feature/xxxx` before implementing or planning a new feature.

Start the full stack with Docker Compose:

```bash
docker compose up --build --wait
```

## Frontend workflow

Run from `apps/frontend/`. This app uses `pnpm@9.15.9`

```bash
pnpm install
pnpm dev        # Next.js dev server with Turbopack
pnpm build
pnpm lint
pnpm format
pnpm format:check
```

## Python workflow

Run from `apps/agent/` or `apps/server/`. All Python commands should use `uv run python ...` .

```bash
uv run ruff format
uv run ruff check --fix
uv run ruff format --check
uv run mypy .
uv run pytest
```

Useful test commands:

```bash
uv run pytest tests/test_foo.py
uv run pytest -k "test_name"
```

## Style notes

* Use Google-style Python docstrings.
* Add type annotations for all Python parameters and return values.

## Pull request expectations
PRs should use the template located at `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`. then check that:

1. Review have been conduced.
2. Corresponding Documentation is updated.
3. The full test suite passes.

## Commits

- Use Conventional Commits for all commit messages.
- Format: `type(scope): summary`
- Example types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
- Keep the summary short and imperative.
- Use `docs:` for documentation-only changes.

Examples:

- `feat(widget): add snapToCorners support`
- `fix(auth): handle flattened token responses`
- `docs(readme): clarify ghost cursor usage`

## What reviewers look for

* Tests covering new behavior.
* Consistent style: code formatted with `uv run ruff format`, imports sorted, and type hints passing `uv run mypy .`.
* Clear documentation for any public API or workflow changes.
* Clean history and a helpful PR description.

参考资料：

• https://code.claude.com/docs/en/memory#write-effective-instructions
• https://code.claude.com/docs/en/memory#how-claude-md-files-load

---

.claude 文件夹

推荐查看官网介绍：链接。比较重要的一些配置：

• .claude/settings.json：配置环境变量，hook 等。
• .mcp.json：可以配置 git mcp，claude 能够读取。
• .claude/skills：比如可以放 security-review skill。
• .claude/agents：放 subagents，比如可以放 code-review.md

部分配置可以考虑放在目录 ~ 下。

---

示例项目

Product Vision 产品愿景
        ↓
Roadmap 产品路线图
        ↓
Epic 代表一个完整的系统能力
        ↓
Feature 可实现的小功能模块
        ↓
Plan 任务计划
        ↓
Implement 开发
        ↓
review 审核

1.0 安装对应推展

安装项目相关的 MCP 或 plugin

---

1.1 Interview

对于零基础开始项目建议先让 agent 面试你一下：

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

Keep interviewing until we've covered everything, then write a complete spec to PRODUCT_SPEC.md.

---

1.2 init

创建 CLAUDE.md 等项目文件。

同时添加上需要的 rules 或者其他要求，如 code style，相关 command。

---

1.3 拆分任务

在使用 claude code 的 plan mode 之前，需要对任务进行拆分（如果你的任务非常大的话）

• 对于特大工程，建议添加 product vision 或者 roadmap，

write a roadmap following the structure of `sample_roadmap.md` for this product:

@PRODUCT_SPEC.md

查看示例 `sample_roadmap.md`

## Summary

A locally runnable, full-stack AI voice agent scaffold built on LiveKit. Two switchable pipeline backends (classic and realtime) give developers a clean starting point for voice AI without rebuilding foundational plumbing each time. All services run under Docker Compose; external API keys are required for model providers.

---

## Version Overview

| Version | Goal                                                    | Status        |
| ------- | ------------------------------------------------------- | ------------- |
| V1      | Working dual-backend voice scaffold                     | In progress   |
| V2      | Visual presence, long-term memory, production hardening | Planned       |
| Future  | Domain-specific agents, multi-user, multimodal          | Not committed |

---

## V1

 **Goal:**  `docker compose up` → voice conversation in browser; both pipeline backends switchable; screen share active; session memory persists within a conversation.

### Epics

| Epic                 | Description                                                  |
| -------------------- | ------------------------------------------------------------ |
| Docker Compose setup | Four services (LiveKit, frontend, agent, token server) boot cleanly from a fresh clone; `.env` template documents all required keys |
...
| Classic pipeline     | Silero VAD → Deepgram Nova-3 STT → Qwen3.7 LLM → Cartesia TTS; pipeline stages individually swappable via config |


### Success Criterion

> Author can `docker comp ose up`, have a voice conversation on either backend, share their screen, and add a new feature without modifying base architecture.

• 对于特定小 feature，可以直接进行 spec 梳理：

spec 有点类似于详细版的 feature，spec 并不是必须的。也可以直接让 agent 根据 feature 制定 plan。这就得看你的上下文情况了，上下文充分时，可以直接掉过 spec 来节省 token 以及人工 review 的时间。

write a spec based on below feature following the `spec_template.md`, 
Do NOT include code examples unless they are absolutely necessary.
Do NOT make technical implementation decisions that belong in the plan.

feature details: 

@feature.md

查看 spec_template

# Spec for <feature-name>

branch: claude/feature/<feature-name>
figma_component (if used): <figma-component-name>

## Summary

...

## Goal

- ...

## Non-Goals

- ...

## Functional Requirements

- ...

## Figma Design Reference (only if referenced)

- File: ...
- Component name: ...
- Key visual constraints: ...

## Edge Cases

- ...

## Acceptance Criteria

- ...

## Open Questions

- ...

## Testing Guidelines

Create a test file(s) in corresponding test folder for the new feature, and create meaningful tests for the following cases, without going too heavy:
- ...

---

1.4 Explore and Plan

• Explore：

read /src/auth and understand how we handle sessions and login. also look at how we manage environment variables for secrets.

• 在 plan mode 下进行项目探索：

write a plan for this feature/spec:

@spec.md

DO NOT WRITE CODE IMPLEMENT. refer to `@sample_plan.md` for structure and content.

切忌让 claude 在 plan 中生成太多的 implementation 代码

查看示例 `sample_plan.md`

# Direct Provider Classic Pipeline Update

- Feature source: xxx
- branch: `feature/xxx`

## Summary

Fix local Docker/self-hosted LiveKit by replacing LiveKit Inference STT/TTS with direct provider plugins. The classic pipeline remains Silero VAD -> Deepgram STT -> Deepseek-compatible LLM -> Cartesia TTS, but Deepgram and Cartesia use their own API keys directly so local `LIVEKIT_API_KEY=devkey` remains only for the self-hosted room server.

## Key Changes

- Add `livekit-plugins-deepgram` and `livekit-plugins-cartesia` to the agent runtime dependencies.
- Require `DEEPGRAM_API_KEY` and `CARTESIA_API_KEY` at agent config import time.
- Change `build_stt()` to return `deepgram.STT(model="nova-3", language="multi", api_key=DEEPGRAM_API_KEY)`.
- Change `build_tts()` to return `cartesia.TTS(model="sonic-3", voice=TTS_VOICE, api_key=CARTESIA_API_KEY)`.
- Keep `build_llm()` on `livekit.plugins.openai.LLM` with `LLM_BASE_URL`, `LLM_API_KEY`, and `LLM_MODEL`.
- Keep `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET` for LiveKit room connection only.
- Update `.env.example` comments to distinguish local room credentials from direct provider API credentials.

## Tests And Verification

- Update config tests to assert missing `DEEPGRAM_API_KEY` and `CARTESIA_API_KEY` fail fast.
- Update provider type tests so `build_stt()` returns `livekit.plugins.deepgram.STT` and `build_tts()` returns `livekit.plugins.cartesia.TTS`.
- Update defaults tests for `STT_MODEL`, `STT_LANGUAGE`, `TTS_MODEL`, and `TTS_VOICE`.
- Run `cd apps/agent && uv run pytest -v`.
- Rebuild and run Docker stack with `docker compose up --build`, start a room from the frontend, send `hi` in chat, and verify:
  - No `agent-gateway.livekit.cloud` `401 Unauthorized` errors appear.
  - Agent logs show chat processing/LLM/TTS progress.
  - The frontend receives an agent response.

## Assumptions

- This is a local self-hosted LiveKit fix, not a migration to LiveKit Cloud.
- Direct provider plugins are preferred because LiveKit recommends model plugins instead of LiveKit Inference for self-hosted deployments.
- The default Cartesia voice is the plugin default unless `TTS_VOICE` is set.
- No frontend changes are needed because the browser already publishes chat to `lk.chat`.

1.5 implement

implement below plan:

@plan_001.md

在 AGENT.md 中设置好 commit 和 PR 的规范，agent 在工作中会经常浏览 commit 以及 PR 历史信息来了解项目情况。

## Pull request expectations
PRs should use the template located at `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`. then check that:

1. Review have been conduced.
2. Corresponding Documentation is updated.
3. The full test suite passes.

## Commits

- Use Conventional Commits for all commit messages.
- Format: `type(scope): summary`
- Example types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
- Keep the summary short and imperative.
- Use `docs:` for documentation-only changes.

Examples:

- `feat(widget): add snapToCorners support`
- `fix(auth): handle flattened token responses`
- `docs(readme): clarify ghost cursor usage`

1.6 review

可以在 IDE 中手动出发 review，也可以用 CodeX 在 github 上对 PR review。

review the implement for below plan:

@plan_001.md

1.7 test

进行端到端的测试，开发者可以更好了解完成情况。

Create an end-to-end testing plan for Feature 7. The plan should include:

1. Use Playwright for end-to-end testing.
2. Add testing tasks for each specification in the design file.
3. Define the expected observations for each test.
4. Store all observations and logs in the `test_output` folder.
5. Record the full testing process, results, issues, and conclusions in a final review document.

Do not start testing until I approve the plan.

---

agent coding 经验

• Include tests, screenshots, or expected outputs so Claude can check itself. This is the single highest-leverage thing you can do.

Strategy	Before	After
Provide verification criteria	”implement a function that validates email addresses"	"write a validateEmail function. example test cases: user@example.com is true, invalid is false, user@.com is false. run the tests after implementing”
Verify UI changes visually	”make the dashboard look better"	"[paste screenshot] implement this design. take a screenshot of the result and compare it to the original. list differences and fix them”
Address root causes, not symptoms	”the build is failing"	"the build fails with this error: [paste error]. fix it and verify the build succeeds. address the root cause, don’t suppress the error”

• Separate research and planning from implementation to avoid solving the wrong problem.

1. Explore ：read /src/auth and understand how we handle sessions and login. also look at how we manage environment variables for secrets.
2. Plan ：I want to add Google OAuth. What files need to change? What's the session flow? Create a plan.
3. Implement ：implement the OAuth flow from your plan. write tests for the callback handler, run the test suite and fix any failures.
4. Commit ：commit with a descriptive message and open a PR
5. small tasks: For tasks where the scope is clear and the fix is small (like fixing a typo, adding a log line, or renaming a variable) ask Claude to do it directly.

• The more precise your instructions, the fewer corrections you’ll need.

Strategy	Before	After
Scope the task. Specify which file, what scenario, and testing preferences.	”add tests for foo.py"	"write a test for foo.py covering the edge case where the user is logged out. avoid mocks.”
Point to sources. Direct Claude to the source that can answer a question.	”why does ExecutionFactory have such a weird api?"	"look through ExecutionFactory’s git history and summarize how its api came to be”
Reference existing patterns. Point Claude to patterns in your codebase.	”add a calendar widget"	"look at how existing widgets are implemented on the home page to understand the patterns. HotDogWidget.php is a good example. follow the pattern to implement a new calendar widget that lets the user select a month and paginate forwards/backwards to pick a year. build from scratch without libraries other than the ones already used in the codebase.”
Describe the symptom. Provide the symptom, the likely location, and what “fixed” looks like.	”fix the login bug"	"users report that login fails after session timeout. check the auth flow in src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it”

• 对于 agents.md 或者 CLAUDE.md，only include things that apply broadly

If Claude keeps doing something you don’t want despite having a rule against it, the file is probably too long and the rule is getting lost. If Claude asks you questions that are answered in CLAUDE.md, the phrasing might be ambiguous.

• claude code 中可以添加 MCP ，如 Notion, Figma 来解决特定问题。
• 通过 skills 来添加 domain knowledge
• claude code 可以使用 subagent 来执行特定任务

Tell Claude to use subagents explicitly: “Use a subagent to review this code for security issues.”

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling

Provide specific line references and suggested fixes.

• 让 agent interview 你

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

• Correct Claude as soon as you notice it going off track.
• 记得清楚无关任务之前的 context 联系。
• Every prompt you send creates a checkpoint. You can restore conversation, code, or both to any previous checkpoint.

---

经验

任务覆盖：

1. 有参考案例代码最好。(using XXX tone and structure as reference.)
2. 好的测试覆盖范围，和接受条件能让 agent 一次搞定工作任务。
3. 最好加上 mcp ，如果有的话。
4. 让 2 个 agent 对比研究报告，或者 plan

write a comparison with the `docs/reference/other_research.md` analysis report:
- points you agree with and that align with your findings;
- points you disagree with, with clear reasoning.