项目文档化为什么先于动手改代码？
- 类比: Coding Agent 首次接触仓库如同新入职工程师，第一天先熟悉结构而非提交代码;
- 第一步: 检查项目是否已有文档;
- 缺文档时: 不应盲目开工，而应主动承担文档化责任——系统阅读代码库，识别主要模块、核心抽象、组件依赖关系;
- 产出: 包含架构概览、目录结构、测试运行指南的初始文档;
- 双重价值: 既为 Agent 后续工作提供蓝图，也为其他开发者提供入门指引;
- 原则: 知识的显式化是高效协作的前提;
项目指令文件是什么？
- 形态:
CLAUDE.md、AGENTS.md、.cursorrules 等，已成业界事实标准;
- 机制: 每次会话开始时被自动注入上下文，相当于项目级系统提示词;
- 与 README 的区别: README 面向人类阅读，指令文件承载面向 Agent 的行为约定;
- 典型条目: 构建与测试命令（“用
pnpm test 而不是 npm test”）、代码风格（“禁用 any 类型”）、明确禁区（“不要改动 migrations/ 目录”）;
指令文件与 SOUL.md、MEMORY.md 如何分工？
| 文件 | 回答的问题 | 生命周期 |
|---|
SOUL.md | Agent 是谁（身份与行为规则） | 跨项目 |
MEMORY.md | 沉淀跨会话经验 | 跨会话 |
| 项目指令文件 | 在这个项目里该怎么干活 | 随仓库版本控制 |
- 同源: 三者是同一思路在不同层面的应用——把隐式知识写成显式文件;
为什么指令文件对上下文工程友好？
- 性质: 内容不随任务变化，是最经济的稳定前缀;
- 收益: 天然对 KV Cache 友好;
- 原则落地: 它是“知识必须存在于代码库本身”最直接的体现;
- 推论: 决策记录在文档里、上下文写在 issue 与 PR 描述里、内部经验沉淀在开发者指南里，Agent 才读得到——对远程工作友好的团队往往也对 AI Agent 友好;
如何评估一个团队的 AI-ready 程度？
- 指标: 一个远程新人只靠代码仓库和文档，能不能独立开展工作;
- 用途: 把团队协作成熟度转化为可观察的判据;