Claude Code 最佳实践：项目目录规范、对话技巧与采访模式

Sat, 15 Mar 2025 00:00:00 +0800

时间锚点：2025-03——Claude Code v0.2.x 时代，规则系统成熟、状态栏 + 计划模式完整配套：0.4 批次 2024-07-28《AI 行业趋势综述》对 Claude Code 的趋势定位

一、Claude Code 是什么

Claude Code 是 Anthropic 官方推出的终端 AI 编程工具——CLI 而非 IDE 插件。2024-2025 年间从"小范围内测"成长为"AI 编程工具三强"之一（与 Cursor / Trae 并列）。

核心定位：

终端 AI——所有交互在命令行
规则驱动——.claude/CLAUDE.md 是项目的"AI 灵魂文件"
计划模式（Plan Mode）——复杂任务先出方案再动手
TDD 友好——天然契合"测试先行"工作流

二、项目级目录结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


project/
├── .claude/
│ ├── settings.json # 项目设置
│ ├── CLAUDE.md # 项目级指令（核心）
│ ├── .mcp.json # 项目级 MCP 服务器配置
│ ├── rules/ # 模块化规则文件
│ │ ├── code-style.md # 代码风格
│ │ ├── testing.md # 测试规范
│ │ └── security.md # 安全要求
│ ├── agents/ # 自定义子代理
│ │ ├── code-reviewer.md
│ │ └── debugger.md
│ ├── skills/ # 自定义技能
│ │ └── fix-issue/
│ │ └── SKILL.md
│ ├── worktrees/ # Git Worktree 目录
│ └── docs/ # AI 生成的文档目录

配置优先级：项目级 > 用户级——项目级 .claude/CLAUDE.md 会覆盖 ~/.claude/CLAUDE.md。

三、CLAUDE.md 模板集

3.1 最小可用模板

1
2
3
4
5
6
7
8


# 构建
- 安装：`npm install`
- 测试：`npm test`
- Lint：`npm run lint`

# 规范
- TypeScript strict 模式
- 提交消息使用 Conventional Commits

3.2 通用项目模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


# 项目：[项目名]
[一句话描述]。技术栈：[列出关键技术]。

# 构建与测试
- 安装：`pnpm install`
- 开发：`pnpm dev`
- 构建：`pnpm build`
- 测试全部：`pnpm test`
- 测试单个：`pnpm test -- path/to/test`
- 类型检查：`pnpm typecheck`
- Lint：`pnpm lint`

# 代码规范
- 使用 ES modules（import/export）
- 函数参数 >3 个时使用对象参数
- 错误处理使用 AppError 类（@src/lib/errors.ts）
- API 路径 kebab-case，JSON 属性 camelCase

# 架构
- 状态管理：Zustand（不是 Redux）
- ORM：Drizzle（不是 Prisma）
- API：tRPC

# 工作流
- **IMPORTANT**: 修改代码后运行 `pnpm typecheck`
- **NEVER**: 不要修改 migrations/ 下的已有文件
- 提交遵循 Conventional Commits

# 压缩指令
When compacting, preserve:
- 修改过的文件完整列表
- 测试命令和结果
- 未完成的任务

3.3 前端项目模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


# 构建命令
- 开发：`pnpm dev`（端口 3000）
- 构建：`pnpm build`
- 测试：`pnpm test`（Vitest）
- E2E：`pnpm e2e`（Playwright）

# 代码规范
- 函数式组件 + hooks
- Tailwind CSS（不用 CSS modules）
- 导入顺序：React → 第三方 → 本地 → 类型 → 样式

# 组件结构
- 页面：`src/app/`（Next.js App Router）
- 组件：`src/components/`
- 参考：`src/components/ui/Button.tsx`

# 测试
- 优先运行单个测试文件
- UI 变更后截图对比验证

3.4 规则文件路径限定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


---
paths:
 - "src/api/**/*.ts"
 - "lib/**/*.ts"
 - "src/**/*.{ts,tsx}" # brace expansion：同时匹配 .ts 和 .tsx
---

# API 开发规范
- 所有 API 端点必须包含输入验证
- 使用标准错误响应格式

四、状态栏（Status Line）

自动配置生成的 status line：

1
2
3
4
5
6
7


{
 "statusLine": {
 "type": "command",
 "command": "npx -y ccstatusline@latest",
 "padding": 0
 }
}

效果：终端底部显示当前模型 / 用量 / 上下文窗口 / 任务状态。

五、8 大核心内置命令

命令	作用
`/init`	初始化 CLAUDE.md
`/btw`	快速提一个附带问题，不中断主对话
`/clear`	清空对话历史，释放上下文空间
`/compact`	清空对话历史，但保留上下文摘要
`/copy`	复制 Claude 最新回复到剪贴板
`/export`	导出当前对话到文件或剪贴板
`/hooks`	查看工具事件的钩子（hook）配置
`/ide`	管理 IDE 集成并显示状态
`/plan`	开启计划模式，或查看当前会话计划
`/rename`	重命名当前对话
`/resume`	恢复之前的对话
`/rewind`	将代码和 / 或对话恢复到之前某个状态
`/tasks`	列出并管理后台任务
`/batch`	分析并规划大规模代码修改，在 5-30 个独立工作区智能体中并行执行
`/loop`	按固定周期重复执行提示词或斜杠命令，例：`/loop 5m check deploy`

六、4 类提示词模板

6.1 高质量提示词结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


┌─────────────────────────────────────────────┐
│ 1. 任务描述 │
│ 做什么？（一句话清晰描述） │
├─────────────────────────────────────────────┤
│ 2. 上下文 │
│ 相关文件：@path/to/files │
│ 参考模式：@path/to/example │
│ 背景信息：为什么要做这个 │
├─────────────────────────────────────────────┤
│ 3. 约束 │
│ 不能做什么 / 必须满足什么 │
│ "不引入新依赖"、"保持向后兼容" │
├─────────────────────────────────────────────┤
│ 4. 验证标准 │
│ 怎么确认做对了？ │
│ "运行 npm test"、"截图对比" │
└─────────────────────────────────────────────┘

6.2 功能开发模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


实现 [功能描述]。

上下文：
- 相关文件：@path/to/relevant/files
- 参考已有模式：@path/to/similar/implementation

要求：
1. [具体要求 1]
2. [具体要求 2]
3. [具体要求 3]

验证：
- 运行 `npm test` 确保所有测试通过
- 运行 `npm run typecheck` 确保无类型错误

6.3 Bug 修复模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


修复 [问题描述]。

复现步骤：
1. [步骤 1]
2. [步骤 2]
3. [出现错误]

错误信息：
[粘贴完整错误信息或堆栈跟踪]

期望行为：[描述正确行为]

请：
1. 找到根因
2. 写一个能复现问题的失败测试
3. 修复问题
4. 确认测试通过

6.4 代码审查模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


审查 @path/to/file 的以下方面：
- 安全漏洞（注入、XSS、认证问题）
- 边界情况处理
- 性能问题
- 与项目现有模式的一致性

对每个问题给出：
1. 问题严重度（Critical / Warning / Suggestion）
2. 具体位置（文件名和行号）
3. 修复建议

七、验证驱动的开发模式（TDD）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


为 @src/utils/date.ts 添加 formatRelativeTime 函数。

要求：
- 输入 Date，输出 "刚刚"、"3 分钟前"、"2 小时前"、"昨天"、"3 天前" 等
- 超过 7 天返回 YYYY-MM-DD 格式

验证：
1. 先为以上每种情况编写测试用例
2. 实现函数
3. 运行 `npm test -- formatRelativeTime`
4. 运行 `npm run typecheck`
5. 所有通过后告诉我结果

核心原则：

先写测试，再写实现
测试失败 → 修复实现
测试通过 → 才算完成

八、规范驱动开发（Spec-Driven）

先写 spec.md → Claude 按规范编码。

1
2
3
4


specs/001-feature-name/
├── spec.md ← WHAT：功能需求（用户故事、验收标准、边界情况）
├── plan.md ← HOW：技术方案（架构设计、数据结构、接口定义）
└── tasks.md ← DO：原子任务（逐步执行指令，每个任务改一个文件）

8.1 4 步走流程

第一步：协作编写 spec.md

1
2
3


> 我想构建 [功能描述]。用采访模式对我进行详细提问，
> 帮我生成一份 spec.md，包含：用户故事、验收标准、边界情况。
> 不要写任何技术实现细节。

第二步：生成 plan.md

1
2
3
4


> @specs/001-feature/spec.md
> 基于这份需求规范，生成技术方案 plan.md。
> 技术栈约束：[TypeScript / React / PostgreSQL]
> 包含：目录结构、核心数据模型、接口定义、实施阶段。

第三步：分解 tasks.md

1
2
3


> @specs/001-feature/spec.md @specs/001-feature/plan.md
> 将技术方案分解为原子任务列表 tasks.md。
> 要求：每个任务只改一个文件，测试先行（奇数任务写测试，偶数任务写实现）。

第四步：逐步执行

1
2


> @specs/001-feature/tasks.md
> 执行任务 T001-T006。严格按 TDD 顺序：先写测试（必须失败），再写实现（使测试通过）。

好处：规范集中在文件里可版本管理，发现问题时先改规范再重新生成。

九、采访模式（AskUserQuestion）

对于大型功能，让 Claude 先采访你以明确需求，而不是一开始就写代码。

AskUserQuestion 是 Claude Code 内置的交互工具——Claude 需要做决策时弹出结构化选择题界面，不需要你打字组织语言，只需点击选项。

9.1 标准采访模板

1
2
3
4
5
6


我想构建 [简要描述]。用 AskUserQuestion 工具对我进行详细采访。

问我关于技术实现、UI/UX、边界情况、顾虑和权衡的问题。
不要问显而易见的问题，深入挖掘我可能没有考虑到的困难部分。

持续采访直到我们覆盖了所有方面，然后把完整的需求规格写入 SPEC.md。

9.2 实战演示：苏格拉底式提问

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


我想开发一款独特的小游戏，但具体做什么、怎么做还没想好。

请你作为游戏策划顾问，用苏格拉底式提问法帮我从零厘清思路。要求：

- 必须使用 AskUserQuestion 工具向我提问，不要用纯文字提问
- 每轮提问后，根据我的回答总结洞察，再发起下一轮提问
- 至少覆盖以下维度：游戏类型、核心玩法、美术风格、目标平台、技术方案
- 灵活运用 single_select、multi_select、rank_priorities 三种题型
- 3-5 轮提问结束后，输出一份「游戏设计一页纸」

从第一轮开始吧。

9.3 引申用法：排查盲区

1
2
3
4
5


对于这个问题，我们还有哪些没有考虑到的？

使用 AskUserQuestion 工具，像苏格拉底一样帮助我，
无论是技术选型、潜在风险、需求对齐等等任何方向，
因为我是小白我什么都不懂，请帮助我理解。

核心思想：把 Claude 从"执行者"变成"顾问"——它不再猜你想要什么，而是通过结构化提问帮你自己想清楚。

最佳实践：完成采访后，开一个新会话来执行规格——新会话有干净的上下文，完全聚焦于实现。

十、Plan Mode：复杂任务的标准做法

1
2
3
4
5
6


claude --permission-mode plan
# 进入 Plan Mode 后
> 阅读 /src/auth 目录，了解我们如何处理会话和登录。
> 同时看看我们如何管理用于密钥的环境变量。
> 我想添加 Google OAuth 登录。需要修改哪些文件？
> 会话流程是怎样的？创建一个实施计划。

Plan Mode 的优势：

不会立即写代码
先阅读现有代码
提出 2-3 个澄清问题
生成可审阅的方案
你可以编辑 / 删改方案
确认后才动手

十一、多会话协作

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 会话 A（Plan Mode）
> 分析 @src/auth 目录，制定添加 Google OAuth 的实施计划

# 会话 B（独立会话）
> 审查这个实施计划 [粘贴计划]。
> 指出遗漏的边界情况、潜在的安全问题、和更好的替代方案。

# 会话 A（继续）
> 按你的计划实现 OAuth 流程。
> 为回调处理器编写测试，运行测试套件并修复所有失败。

好处：

上下文干净（每个会话聚焦一件事）
独立审查（避免 Claude 自我肯定）
失败易回滚

十二、增量开发技巧

写一个文件 → 测试 → 继续——尽早发现问题
如果 Claude 偏离方向，按 Esc 立即停止
按两次 Esc 或 /rewind 回到之前的检查点

十三、客户端工具配套

1
2
3
4
5
6
7
8
9


# gh - GitHub 官方 CLI
brew install gh
gh auth login

# jq - JSON 解析器
brew install jq

# ripgrep - 高速代码搜索
brew install ripgrep

这些工具让 Claude Code 在 shell 里能完成 90% 的工作流。

十四、配置相关命令

命令	作用
`/agents`	管理智能体（agent）配置
`/effort`	设置模型使用的思考 / 努力程度
`/mcp`	管理 MCP 服务器
`/memory`	编辑 Claude 记忆文件
`/model`	为 Claude Code 设置 AI 模型
`/permissions`	管理工具使用的允许 / 禁止权限规则
`/plugin`	管理 Claude Code 插件
`/update-config`	通过 settings.json 配置核心行为

十五、Git 相关命令

命令	作用
`/add-dir`	添加新的工作目录 [path]
`/branch`	在当前位置为对话创建一个分支 [name]
`/diff`	查看未提交变更与每轮对话的差异对比
`/pr-comments`	获取 GitHub PR 的评论（优先 gh 工具）
`/review`	审查一个 PR（优先 gh 工具）
`/security-review`	对当前分支未提交变更完成安全审查
`/simplify`	检查修改后的代码，优化复用性 / 质量 / 效率

十六、统计命令

命令	作用
`/config`	打开配置面板
`/context`	以彩色网格形式可视化当前上下文占用情况
`/cost`	显示当前会话总消耗费用与时长
`/skills`	列出可用技能
`/stats`	显示 Claude Code 使用统计与活动记录
`/status`	显示状态：版本、模型、账号、API 连接、工具状态
`/insights`	生成分析报告，总结 Claude Code 会话使用情况

十七、避坑指南

不要在根目录建 docs/——.claude/docs/ 才是 AI 文档区
rules 不要全部堆在一个 CLAUDE.md——按模块拆 rules/code-style.md / rules/testing.md 等
大改动必开 Plan Mode——避免一上来改 20 个文件后才发现方向错
TDD 是 Claude Code 的最佳搭档——“先写失败测试"能逼出 Claude 思考边界情况
采访模式胜过纯文字提问——选择题界面比打字快 3 倍
多会话审查——Plan Mode 一个会话，实现另一个会话，审查第三个会话
/rewind 是后悔药——按两次 Esc 或 /rewind 回到检查点
/compact 释放上下文——对话变长后用 /compact 保留摘要释放窗口

十八、总结

Claude Code 的差异化在”终端 + 计划模式 + 规范驱动"——把"AI 编程"从"编辑器补全"升级为"工程化实践"。

适合：

习惯终端的开发者
服务端 / 远程开发
严格 TDD 团队
喜欢"先规范后实现"工作流

不适合：

只想 Tab 补全（用 Cursor / Copilot）
不习惯命令行的纯前端（用 Trae / Cursor）

实战建议：

项目级 CLAUDE.md 是核心——写好等于一个永不离职的初级工程师
rules 按模块拆——不要全堆一起
TDD + Plan Mode——大改动的标准组合
采访模式——把 Claude 当顾问用，不是当搜索引擎
多会话协作——Plan / 实现 / 审查分开

下一步：可参考 2024-09-15《Cursor 实战》对比 IDE 类 AI 工具；2025-06-15《AI IDE 横评》看 6 款工具全景对比。

2024+ 视角：Claude Code v0.3+ 新特性与 AI 编程工具新格局

Claude Code v0.3+（2025 路线图）核心变化

Sub-agents GA：子代理完整支持，可独立任务、独立上下文
Skills 系统成熟：可复用工作流，跨项目共享
Multi-modal 输入：支持图片直接喂入（架构图、错误截图）
Worktree 集成：自动创建独立 worktree 做实验性改动
Plan Mode 增强：可生成可执行的实施清单 + 验收标准

v0.3+ 新增命令

命令	作用
`/worktree`	快速创建 git worktree 隔离工作区
`/batch`	5-30 个独立工作区智能体并行执行
`/loop`	周期性执行提示词（自动化 CI 任务）
`/agents`	管理 sub-agent 配置
`/effort`	设置模型思考深度（low/medium/high）
`/simplify`	自动检查并优化代码质量
`/security-review`	自动安全审查
`/insights`	生成会话分析报告
`/rewind`	回到对话检查点（“后悔药”）

Skills 系统：从"配置"到"工作流"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# skills/fix-issue/SKILL.md
---
name: fix-issue
description: 修复 GitHub Issue 的标准工作流
---

# Fix Issue Workflow

1. 读 issue 描述
2. 在 codebase 里搜索相关代码
3. 写失败测试
4. 实现修复
5. 验证测试通过
6. 提交 PR，关联 issue

1
2


# 调用 skill
> /fix-issue #123

Sub-agents：复杂任务并行化

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# agents/code-reviewer.md
---
name: code-reviewer
description: 自动审查 PR 的代码
tools: [Read, Grep, Bash]
---

你是严格的代码审查员。审查 PR 改动，给出：
1. 安全问题
2. 性能问题
3. 与项目风格的一致性

按严重度（Critical / Warning / Suggestion）输出。

1
2


# 主线程委派
> 用 code-reviewer sub-agent 审查 PR #456

AI 编程工具 2024+ 格局

工具	定位	2024+ 状态
Claude Code	终端 AI + 计划模式	差异化在 Plan + Spec 驱动
Cursor	IDE 内 AI（VS Code fork）	编辑器内补全最强
Trae	ByteDance 出品，IDE AI	国内访问稳定
Cody	Sourcegraph 出品	企业代码库深度集成
GitHub Copilot	微软出品	市场份额最大（40%+）
Codeium / Windsurf	免费替代	速度最快
Continue	开源	VS Code 插件，自定义 LLM
Aider	终端 AI（Python）	适合 Python 项目

2024+ 范式：“Spec-Driven + TDD + Multi-Agent”

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


用户提出需求
 ↓
[Agent 1: 采访模式] → spec.md
 ↓
[Agent 2: 架构师] → plan.md
 ↓
[Agent 3: 任务分解] → tasks.md
 ↓
[Agent 4-N: 实现] → 代码 + 测试（TDD）
 ↓
[Agent N+1: 审查] → 优化建议
 ↓
合并 → PR

LLM 选型 2024+ 演进

模型	适用	2024+ 状态
Claude 4 Sonnet / Opus	复杂推理 + 大上下文	编程 SOTA
GPT-4o / GPT-4 Turbo	通用	速度 + 多模态
DeepSeek V3 / R1	推理强 + 免费	国内首选
通义千问 Qwen-Coder	中文 + 代码	阿里云
Qwen 2.5-Coder-32B	开源 + 强	本地部署首选
Code Llama 70B	Meta 出品	企业私有部署
Devin	AI 工程师代理	尚未完全 GA

实战坑（2024+）

Claude Code 的 --permission-mode 谨慎使用 bypassPermissions——子代理可能误删文件
/rewind 不是万能——只回退代码，不回退已 push 的 commit
Skill 文件 frontmatter 必须符合 YAML 规范，否则加载失败
Sub-agent 上下文独立——主线程看不到子代理的过程输出，只看结果

2024+ 推荐组合

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


个人开发
├── Claude Code + Claude 4 Opus
├── Cursor + Claude 4 Sonnet（IDE 内）
└── Continue + DeepSeek V3（免费日常）

企业团队
├── Claude Code 团队版（统一计费 + 共享 skills）
├── Cursor Business（企业 SSO）
├── 自建 Qwen2.5-Coder-32B（敏感代码本地化）
└── 规范驱动工作流（spec.md / plan.md / tasks.md）

Tdd on Liangweidong's blog