为什么上下文决定结果
每次 Claude Code 会话都有新的上下文窗口。它可以重新读取仓库，但不会天然知道团队习惯、禁止事项、验证命令和“完成”的定义。官方提供 CLAUDE.md 和自动记忆两种跨会话机制，其中团队规则应优先写进可审查的 CLAUDE.md。
创建项目 CLAUDE.md
在仓库根目录运行 /init 可以生成起点，但生成结果仍需要人工精简。一个实用的文件应包含可验证事实：
# Project guide
## Repository layout
- `src/app/`：页面与路由
- `src/lib/`：内容服务和领域逻辑
- `content/`：正式 Markdown 内容
## Commands
- `npm run typecheck`：TypeScript 检查
- `npm test`：单元测试
- `npm run build`：内容校验和生产构建
## Working agreements
- 修改前先读取相邻实现和测试。
- 不覆盖用户已有的未提交修改。
- 新增公开内容前运行内容校验。
- 完成时汇报执行过的命令和实际结果。
规则应具体、简短，而且能通过命令或代码审查验证。“保持高质量”几乎没有约束力；“修改 TypeScript 后运行 npm run typecheck”则清晰得多。
与 AGENTS.md 共存
Claude Code 读取 CLAUDE.md，不会自动把 AGENTS.md 当作自身指令。仓库已经使用 AGENTS.md 时，可以在 CLAUDE.md 中导入它：
@AGENTS.md
## Claude Code
- 大范围改动前先进入计划阶段。
- 不修改 `.env` 和生产密钥文件。
这样可以复用通用规则，同时保留 Claude Code 专属说明。外部导入首次出现时可能需要确认，团队应检查导入目标是否可信。
分层与局部规则
Claude Code 可以从多个作用域读取说明：
~/.claude/CLAUDE.md：个人跨项目偏好。- 仓库根目录
CLAUDE.md：团队共享规则。 - 子目录中的
CLAUDE.md：靠近特定模块的规则。 CLAUDE.local.md：不提交 Git 的个人项目说明。.claude/rules/*.md：可以按路径组织的专题规则。
不要把所有内容塞进一个超长文件。官方建议保持简洁；复杂操作流程更适合拆成规则或技能，只在相关任务中加载。
写好当前任务
持久规则不能替代当前任务说明。一个稳定的任务至少应包含：
目标：修复教程详情页在移动端横向溢出的问题。
范围：只修改教程布局和相关测试，不重构内容服务。
上下文：问题出现在 390px 宽度；代码块和表格必须继续支持横向滚动。
完成条件：
1. 新增能够复现问题的测试；
2. 390px 下页面宽度不超过 viewport；
3. typecheck、测试和 build 通过。
明确范围和完成条件，可以减少代理在没有授权时扩大改动。
检查 Claude 是否理解
在开始重要任务前，让 Claude Code复述约束：
在修改前，请列出你读取到的项目规则、计划修改的文件和验收命令。
如果规则之间有冲突，先指出冲突，不要自行选择。
如果输出遗漏关键规则，优先修改 CLAUDE.md 的结构和表达，而不是在每次会话中重复纠正。