Project Doctrine：构建AI代理可理解的“项目学派”与判断力传承系统

1. 项目概述：什么是 Project Doctrine？

如果你和我一样，长期与 AI 代理（比如 Claude Code、Cursor、Codex 等）协作开发项目，一定遇到过这个令人头疼的场景：昨天你和代理花了整整一下午，通过反复试错和讨论，终于敲定了一个核心架构决策——比如“所有 UI 状态必须由确定性运行时代码管理，LLM 只负责生成语义块”。今天你开一个新会话，满怀信心地告诉代理：“继续昨天的项目。”结果它转头就给你提了一个方案，把按钮的回调逻辑直接塞进了 LLM 的提示词里。那一刻，你仿佛听到昨天那个下午“啪”的一声，消失了。

这就是典型的“手递手”交接的局限。它告诉代理“发生了什么”和“接下来做什么”，但它无法传递“为什么要这么做”以及“如何判断什么是对的”。你的项目在成长中积累的那些宝贵的、用时间和错误换来的“项目直觉”或“团队共识”，在每次会话重启时，都被重置了。

Project Doctrine就是为了解决这个问题而生的。它不是另一份架构文档，也不是会议纪要。你可以把它理解为一个项目的“判断力传承系统”或“项目学派养成手册”。它的核心目标非常明确：将项目中那些来之不易的经验、教训、品味和决策逻辑，转化为一种可被 AI 代理持续理解和运用的“上下文”。简单说，它教 AI 用你的方式思考，用项目的标准判断。

想象一下，你为项目培养了一位永不离职、且能瞬间理解项目所有历史背景和潜规则的“资深成员”。这就是 Doctrine 要达成的状态。它通过一套结构化的文件体系（一个“技能”包），捕获从核心意识形态到具体失败案例的一切，确保项目的判断连续性，而不仅仅是工作连续性。

2. 核心理念与价值：为什么“手递手”远远不够？

在深入具体操作前，我们必须先统一思想：为什么现有的“手递手”模式会失效？理解了这一点，你才能明白 Doctrine 每个设计背后的深意。

2.1 “手递手”的天然缺陷

“手递手”文档通常回答三个问题：

1. What happened?（刚才发生了什么？）
2. What changed?（代码/状态有什么变化？）
3. What‘s next?（接下来该做什么？）

这很好，对于延续一个具体的、短期的任务链足够了。但它天然缺失了另外三个维度的信息：

1. Why was this chosen?（当初为什么选这个方案？另一个看似合理的方案为什么被毙了？）
2. What looks good but is actually bad?（哪些做法看起来聪明，实则是陷阱？）
3. What does “good” look like here?（在这个项目里，“优秀”的输出具体长什么样？）

“手递手”记录的是事件和指令，而 Doctrine 记录的是判断的逻辑和决策的上下文。前者是“流水账”，后者是“兵法”。

2.2 Doctrine 的核心价值：构建“项目学派”

任何一个严肃的项目，在发展到一定阶段后，都会自然形成一个独特的“学派”。这个学派包含：

• 信念与禁忌：我们坚信什么？我们坚决反对什么？（L1: 意识形态）
• 已验证的方法：什么事怎么做最靠谱？（L3: 方法）
• 品味的具象化：什么是“对味”，什么是“跑偏”？（品味示例）
• 伤疤与教训：我们曾为哪些错误付出过代价？（L6: 核心方法 / 失败记忆）
• 共享的语言与思维模式：我们如何讨论问题？（L5: 思维模式）

Doctrine 的价值，就是把这个隐性的、存在于核心成员脑海中的“学派”显性化、文档化、结构化。它让新加入的 AI 代理（甚至新加入的人类成员）不再是“一张白纸”，而是能带着这个项目的“前置经验”开始工作。

实操心得：不要试图在项目第一天就创建完整的 Doctrine。那时项目还没有“伤疤”，没有经历过真正的权衡和取舍，写出来的只能是空洞的愿景或教条。最好的启动时机是“骨架已成，混乱未起”之时——即核心功能跑通后，你开始与代理进行多次高语境会话，并已经纠正过它几次“方向性错误”的时候。

3. 六层结构模型：Doctrine 的骨架与灵魂

Project Doctrine 采用一个精心设计的六层模型来组织信息。这六层不是简单的分类，而是一个从“道”到“术”、从“永恒”到“瞬时”、从“原则”到“伤疤”的完整认知体系。

3.1 L1 - 意识形态层：什么必须永远为真？

这是项目的“宪法”，是那些不容妥协的核心理念和信任边界。

• 内容：产品哲学、核心设计原则、非功能性需求（如性能、安全底线）、技术选型的根本原因、数据所有权等。
• 示例：“本项目的 UI 渲染层必须与业务逻辑完全解耦，所有用户交互状态由前端框架（如 React/Vue）的确定性运行时管理，LLM 仅输出语义化的 JSON 结构。”
• 写法要点：每条都应像法律条文一样清晰、无歧义。避免使用“应该”、“尽量”等模糊词汇，多用“必须”、“禁止”。每条背后最好能简述其“立法理由”。

3.2 L2 - 知识层：什么在当下为真？

这是项目的“实时快照”，反映当前状态。

• 内容：当前开发阶段（如 Alpha、Beta）、已发布版本、最近的重要提交、开放中的阻塞性问题、已知的文档过时部分。
• 示例：“当前处于 v0.8.0 Beta 阶段，重点在优化性能。feature/auth-overhaul分支的合并是当前最高优先级，但被 #123 号 issue 中描述的第三方库兼容性问题阻塞。”
• 写法要点：这是更新最频繁的层。需要定期（如每天或每次重大变更后）维护。它确保代理对项目现状的认知与你同步，避免基于过时信息做决策。

3.3 L3 - 方法层：什么被证明是有效的？

这是项目的“最佳实践库”，记录那些经过验证的工作流和模式。

• 内容：如何规划一个新功能、代码审查的检查清单、测试策略、部署流程、调试特定问题的步骤。
• 示例：“添加新 API 端点时，遵循‘契约先行’原则：先在openapi.yaml中定义清晰的接口规范，生成 Mock 服务，再进行前后端并行开发。”
• 写法要点：要具体、可操作。不要写“要写好测试”，而要写“单元测试覆盖率目标为 80%，新增业务逻辑必须包含集成测试，使用jest配合supertest进行 API 测试。”

3.4 L4 - 标准作业程序层：什么应该被重复执行？

这是项目的“操作手册”，针对重复性任务的标准解法。

• 内容：发布新版本的步骤、处理用户反馈的流程、数据库迁移 SOP、日志排查 SOP。
• 示例：“生产环境热修复 SOP：1. 从main切出hotfix/分支；2. 修改必须附带回归测试；3. 通过 CI/CD 全流程；4. 合并后立即在监控面板观察错误率 15 分钟。”
• 写法要点：写成一步步的检查清单或流程图。目标是让一个不熟悉该任务的人或代理，能按图索骥无误完成。

3.5 L5 - 思维模式层：应该如何思考？

这是项目的“心智模型工具箱”，定义在不同场景下应采用的推理框架。

• 内容：证据优先模式、辩证讨论模式、确定性执行模式、品味评审模式、安全闸门模式等。
• 示例：“安全闸门模式：当变更涉及用户数据、支付或核心权限时，必须切换至此模式。思考顺序为：1. 最坏情况影响是什么？2. 是否有回滚方案？3. 是否需要额外审计或人工批准？”
• 写法要点：为每种模式起一个鲜明的名字，并清晰定义其触发条件、核心问题和输出要求。这能极大提升与代理沟通的效率，你可以直接说：“请用‘证据优先模式’分析这个性能问题。”

3.6 L6 - 核心方法层：项目用代价换来了什么？

这是项目的“伤疤记忆”，是最有价值也最难写的一层。它记录那些用痛苦换来的、压缩后的经验法则。

• 内容：简练的格言、血泪教训、反模式警示。每一条都必须有具体的失败案例作为起源。
• 示例：“L6-1：不要信任 LLM 生成的 ID。起源：FM-2（失败记忆第2条），曾因让 LLM 生成数据库主键导致重复键冲突和数据混乱。正确做法：所有唯一标识符必须在后端确定性生成。”
• 写法要点：严禁鸡汤和口号。每一条都必须能追溯到一次具体的、痛苦的失败。格式通常是“不要做 X，要做 Y”，并附上简短的原因和起源索引。

注意事项：很多初学者容易把 L1（意识形态）和 L6（核心方法）混淆。一个简单的区分方法是：L1 是“我们信仰什么”，它通常源于创始愿景或第一性原理；L6 是“我们学会了什么”，它一定源于一次具体的失败或惊喜的发现。L1 告诉你目标，L6 告诉你路上有哪些坑。

4. 核心文件解析：超越六层的实战利器

除了六层模型文件，Doctrine 技能包里还有几个“特种武器”，它们在传递“判断力”方面往往比状态快照更重要。

4.1 失败记忆：将陷阱标记在地图上

failure-memory.md可能是你最先能写出干货的文件。它系统化地记录那些“看起来合理，实则有毒”的决策。

• 标准结构：

  1. 诱惑：那个错误方案当时为什么看起来有吸引力？（例如：“让 LLM 直接生成 HTML 按钮代码，看起来能快速实现动态 UI。”）
  2. 如何失败：具体是怎么搞砸的？（例如：“导致 UI 行为不可预测，无障碍属性缺失，且与前端框架状态管理冲突，难以调试。”）
  3. 未来如何检测：以后怎么提前嗅到这个陷阱的味道？（例如：“任何计划中，如果 LLM 的输出直接变成了可执行的 UI 组件、回调函数名或状态标识符。”）
  4. 正确做法：应该怎么做？（例如：“LLM 输出结构化的意图描述，如{action: 'confirm', target: 'item_123'}，由前端的确定性渲染器将其转换为具体的 UI 元素和事件绑定。”）

• 实操心得：撰写失败记忆时，心态要像科学家记录实验失败，而不是法官宣判。目的是形成“免疫记忆”，而不是追责。好的失败记忆条目，能让代理在提出类似方案时，自己就产生“警觉”。

4.2 品味示例：展示“好”与“不够好”的对比

taste-examples.md用具体的、对比的案例来定义抽象的“项目品味”。形容词是苍白的，对比是强大的。

• 标准结构：
  • 场景：简要描述一个设计或决策点。
  • 不够好：展示一个符合通用标准但不符合本项目品味的方案，并解释其缺点。
  • 好：展示本项目认可的方案，并解释其优点。
  • 为何“好”胜出：从项目核心价值（如可维护性、用户体验一致性、性能）角度深入分析。
• 示例：
  • 场景：处理用户删除操作的确认。
  • 不够好：代理在对话中说：“要我帮你删除这个文件吗？”（这创造了“对话剧场”，但未触发任何实际的、可撤销的确认流程）。
  • 好：UI 呈现一个标准的确认对话框，标题为“删除文件？”，并带有“取消”和“永久删除”两个按钮，删除操作记录在审计日志中。
  • 为何“好”胜出：后者提供了可预测的、可访问的、且具备安全边界的产品行为，符合 L1 中“用户操作必须明确且可追溯”的原则。

4.3 学徒检验：验证代理是否“入门”

apprenticeship-check.md是一组问题，用于在新代理会话开始时，检验它是否真正消化了 Doctrine 的精髓，而不是仅仅“读过”了文件。

• 典型问题：
  1. 根据当前状态（L2），我们现在处于项目的哪个阶段？当前最大的障碍是什么？
  2. 根据意识形态（L1），如果有一个功能请求要求快速但破坏解耦，我们应该如何回应？
  3. 请回忆一个失败记忆（FM）中的例子，并说明如果遇到类似诱惑，你会如何避免。
  4. 针对“为用户添加一个反馈按钮”这个任务，你会启动哪种思维模式（L5）来规划？第一步是什么？
• 作用：这不仅是对代理的测试，更是对你所编写 Doctrine 质量的检验。如果代理无法清晰回答这些问题，说明你的 Doctrine 可能还不够具体或深入。

4.4 引导提示词：启动标准化会话

bootstrap-prompt.md是一个预设的提示词，用于在每次新会话开始时，一键式地为代理加载整个 Doctrine 上下文。它的内容通常是：

你正在参与 [项目名] 的开发。请首先仔细阅读并理解位于 `[技能路径]` 下的 Project Doctrine 技能包中的所有内容，特别是 state-snapshot.md, layer-1-ideology.md, 和 failure-memory.md。在开始任何实质性工作前，请先根据 apprenticeship-check.md 中的问题，简要陈述你对项目当前状态、核心原则和主要风险的理解。

将这个提示词保存到你的 AI 开发工具（如 Cursor、Claude Code）的预设提示词或AGENTS.md文件中，可以极大简化每次的启动流程。

5. 实战工作流：从零构建你的第一个 Doctrine

理论说了这么多，现在让我们动手，在 30 分钟内创建一个最小可行 Doctrine。记住 MVD 的原则：从能立刻产生价值的最小集合开始，仅当缺失某个文件让你感到痛苦时，才去补充它。

5.1 第一步：准备技能模板

1. 获取模板：克隆或下载fagemx/project-doctrine仓库。
2. 放置技能：根据你使用的 AI 代理运行时，将templates/project-doctrine-skill/目录复制到相应位置：
   • Claude Code (项目级)：复制到项目根目录的.claude/skills/your-project-doctrine/
   • Cursor：复制到docs/skills/your-project-doctrine/，并在.cursor/rules/中添加一个指向它的规则文件。
   • 通用代理：复制到docs/skills/your-project-doctrine/，并在项目根目录的AGENTS.md或GEMINI.md中引用它。
3. 重命名：将技能目录名中的your-project替换为你实际的项目名称。

5.2 第二步：填充核心四文件（30分钟挑战）

不要试图一次性填满所有文件。集中精力完成以下四个，就能立刻获得 80% 的收益。

1. state-snapshot.md(5分钟)：回答“我们现在在哪？”

   • 当前版本/分支。
   • 刚刚完成的主要工作。
   • 接下来 1-2 天要解决的头号问题。
   • 已知的、最令人头疼的技术债或 Bug。
   • 写法：用项目日志或待办事项列表的口吻，简洁列出事实。

2. layer-1-ideology.md(10分钟)：回答“我们绝不妥协的是什么？”

   • 写下3条你最核心、最不容挑战的项目原则。例如：
     • “数据层必须完全独立于 UI 框架。”
     • “所有用户输入必须在首次接触时进行验证和清理。”
     • “错误信息必须对用户友好，同时对开发者可调试。”
   • 写法：每条原则用一句话阐明，可以加一句简短的理由。

3. failure-memory.md(10分钟)：回答“我们别再掉进那个坑了！”

   • 写下3个你或你的代理最近犯过的、让你捶胸顿足的错误。
   • 为每个错误套用“诱惑 -> 失败 -> 检测 -> 正确做法”的结构。
   • 写法：描述要具体，像在写一个事故复盘报告。

4. bootstrap-prompt.md(5分钟)：创建一键启动提示词。

   • 参考上文示例，修改项目名和路径。
   • 将其设置为你的 AI 开发工具的默认会话开场白。

5.3 第三步：集成与测试

1. 集成：在你的 AI 代理配置中，确保它能读取到你放置的技能目录。
2. 首次测试：开启一个全新的代理会话，使用你的bootstrap-prompt.md。
3. 验证：向代理提问，检验它是否理解了状态快照、是否记住了那三条核心原则、是否能复述一个失败记忆。如果它答得上，你的 MVD 就成功了！

避坑指南：在填充文件时，务必抵抗两个诱惑：一是“完整性强迫症”，觉得每个文件都必须填满；二是“文档债务”，用空洞的废话去填充模板。Doctrine 的信条是：如果一个文件的缺失没有让你感到切实的痛苦，那就让它空着。只记录那些真正流过血、换来的教训。

6. 三种应用模式：选择适合你的姿势

Project Doctrine 不是一成不变的，它支持三种不同的应用模式，对应不同的协作场景。

6.1 个人模式：你与你的代理军团

• 场景：你是项目的唯一或主要开发者，主要与 AI 代理协作。
• 核心比喻：Doctrine 是“给未来自己和代理的外接记忆”。
• 特点：
  • 低仪式感：更新无需评审，直接修改。可以用更个人化、随意的口吻。
  • 快速迭代：一旦发现认知偏差或新教训，立刻更新 Doctrine。
  • 重点在 L6 和失败记忆：记录你与代理互动中产生的独特教训。
• 操作：直接使用 Solo Mode 指南，将技能包放在你的项目本地即可。

6.2 团队模式：人类与代理的混合团队

• 场景：多人（可能包括多名开发者和多个 AI 代理）共同维护一个代码库。
• 核心比喻：Doctrine 是“人类与代理之间的共享判断契约”。
• 特点：
  • 需要治理：Doctrine 的修改需要经过团队评审（如 PR 流程），因为它成了团队共识。
  • 去个人化：失败记忆要避免指向具体个人，应描述为“团队曾采取的一种方法…”。
  • 新增文件：需要governance.md（定义如何更新 Doctrine）和decision-records.md（记录重大决策的背景）。
  • 价值巨大：能极大减少团队成员间的上下文同步成本，让新成员（无论是人还是 AI）快速上手。
• 操作：遵循 Team Mode 指南，将 Doctrine 视为重要的项目资产进行管理。

6.3 考古模式：理解一个陌生项目

• 场景：你要为一个已有的开源项目或遗留系统贡献代码，需要快速理解其“潜规则”。
• 核心比喻：“分析决策，而非人格；推断规范，而非动机。”
• 特点：
  • 推断而非规定：你通过分析项目的 PR、Issue、代码审查意见、提交历史等公开工件，来反向推导其可能的 Doctrine。
  • 标注置信度：每条推断出的规则都要注明证据来源和你的置信度（高/中/低）。
  • 目的明确：是为了减少你提交的 PR 被拒绝的几率，更快地融入项目，而不是给项目定规矩。
  • 伦理要求：只分析公开的、技术性的决策模式，绝不揣测维护者个人动机或制造是非。
• 操作：使用 Archaeology Mode 模板，像一个人类学家一样系统地收集和分析项目痕迹。

6.4 模式选择流程图

开始 -> 你是在主导自己的项目吗？ -> 是 -> 主要和AI协作？ -> 是 -> 【选择个人模式】 -> 是 -> 和多人/多代理协作？ -> 是 -> 【选择团队模式】 -> 否 -> 你要参与一个已有项目？ -> 是 -> 【选择考古模式】 -> 否 -> 项目很小或一次性？ -> 是 -> 【暂不需要Doctrine，README足够】

7. 日常使用与维护：让 Doctrine 保持活力

Doctrine 不是创建完就束之高阁的文档。它需要被使用，也需要被维护，否则就会变成另一份过时的“祖传代码”。

7.1 何时使用 Doctrine？

在以下五个关键时刻，养成习惯去“咨询” Doctrine：

1. 开启新会话时：这是强制动作。使用bootstrap-prompt让代理加载上下文。
2. 规划大型任务前：在脑暴或编写详细计划前，快速浏览 L1（意识形态）和 L6（核心方法），确保方向不偏。
3. 评审设计方案时：用 Doctrine 作为评审清单。这个方案有没有触犯失败记忆里的禁忌？是否符合我们的品味示例？
4. 同一个错误第二次出现时：立即停下来，将这次事件整理成一个新的失败记忆条目。
5. 达成重大里程碑后：在发布新版本或完成一个重要阶段后，更新state-snapshot.md，并回顾是否有新的经验可以提炼到 L3（方法）或 L6（核心方法）中。

什么时候可以不用？修改错别字、格式化代码、查找简单的 API 用法时，不需要惊动 Doctrine。

7.2 如何维护与更新？

Doctrine 应该像代码一样被维护，遵循“小而精，而非大而全”的原则。建立一个轻量级的维护流程：

1. 定期回顾：设定一个节奏（如每两周或每个冲刺周期结束），花 15 分钟快速浏览 Doctrine。
2. 信息分拣：当发生重要事情时，判断其归属：
   • 保留：信息仍然有效，无需改动。
   • 晋升：一次性的“手递手”观察，被证明具有普遍价值，将其提炼为正式的失败记忆、品味示例或 L6 条目。
   • 归档：信息已过时（如旧版本的状态），但仍有历史参考价值。将其移至references/archive/目录，并注明失效日期。
   • 删除：信息重复、错误或不再有任何判断价值。直接删除，Git 历史会保存记录。
3. 孵化区：创建一个references/incubation.md文件。对于不确定是否要放入正式 Doctrine 的观察或想法，先扔到这里。在定期回顾时再决定其命运。
4. 核心原则：Doctrine 应该随着时间的推移变得更小、更锋利，而不是更庞大、更笨重。不断合并、提炼、删除过时的内容，确保每一条都像手术刀一样精准有用。

实操心得：维护 Doctrine 最大的敌人是“完美主义”和“拖延症”。不要想着一次性把它修得完美。采用“增量更新”和“及时止损”策略。每次会话后，如果有一个强烈的“啊哈！”或“哎呀！”时刻，花 2 分钟把它记下来。积累的力量远大于一次性的宏大工程。

8. 常见问题与疑难解答

在实际应用 Project Doctrine 的过程中，你可能会遇到一些典型问题。以下是我根据经验整理的排查清单。

最后，记住 Project Doctrine 的终极心法：它不是用来总结项目的，而是用来萃取项目的“学派”的。你的目标不是创建一份无所不包的百科全书，而是锻造一把锋利的、能传承判断力的钥匙。从最小可行版本开始，让它与你和你代理的协作共同进化，你会发现自己花在纠正方向、重复解释上的时间越来越少，而用于创造价值的精力越来越多。这，正是高效协作的本来面目。