1. 项目概述为什么你的AI助手总是“记不住事”如果你和我一样深度依赖AI助手比如Claude Code、Cursor、Codex来推进项目那你一定遇到过这个令人抓狂的场景昨天你和助手花了两个小时终于敲定了一个核心架构决策——比如“所有UI渲染必须与业务逻辑解耦由确定性运行时代码控制”。今天你开一个新会话满怀期待地输入“继续昨天的UI模块开发”结果助手给出的方案赫然又是把按钮回调直接塞进LLM的输出里。你不得不停下来重新解释一遍“不我们昨天不是这么定的……”这不是AI的错也不是你的错。问题在于我们传递给AI的“上下文”或“交接文档”Handoff本质上是一份事件流水账。它记录了“发生了什么”、“改了什么”、“下一步该做什么”但它丢失了项目中最重要的东西判断力Judgment。流水账告诉AI“手”该往哪动但没教会它“脑”该怎么想。这就是Project Doctrine要解决的核心痛点。它不是一个更详细的README也不是一份架构说明书。它的定位非常独特将项目在漫长开发中积累的“血泪教训”、“审美偏好”和“决策逻辑”固化下来形成一个可被AI理解和继承的“项目学校”Project School。当你对助手说“先读一下项目信条Doctrine”你是在邀请它进入这个项目的“思维结界”用项目本身的价值观和经验去思考而不是从零开始或套用通用模式。简单来说Handoff解决的是“工作连续性”Work Continuity而Doctrine解决的是“判断连续性”Judgment Continuity。前者让你接着干后者让你接着“对”。2. 核心理念拆解从“事件记录”到“判断传承”要理解Doctrine的价值我们需要先看清当前AI协作模式的局限性。大多数项目与AI的交互停留在“会话级”的临时记忆。一个典型的Handoff文件可能包含当前状态我们刚刚完成了用户登录模块的API。最近更改修复了/api/login端点的一个空指针异常。待办事项接下来需要实现前端登录页面。这份文档对启动下一个会话很有用。但它没有回答更深层的问题为什么选择JWT而不是Session是因为无状态扩展性还是因为移动端兼容哪些看似合理的方案是我们踩过坑后坚决避免的比如为什么不让LLM直接生成包含onClick的HTML什么样的代码才符合这个项目的“气质”是追求极致的函数式纯度还是务实至上、可读性第一Doctrine的六层模型Six-Layer Model就是为了系统性地回答这些问题。它不是凭空创造的而是对成熟软件团队中那些“只可意会”的隐性知识的显性化封装。一个健康的项目就像一个有生命的组织会自然演化出自己的“信念”、“禁忌”、“品味”和“方法论”。Doctrine就是把这个演化过程的结果结构性地记录下来。2.1 六层模型详解构建你的“项目大脑”Project Doctrine的核心框架是一个六层结构由浅入深从“是什么”到“为什么”构建起完整的判断体系。L1 — 意识形态层Ideology这是项目的“宪法”是那些历经版本迭代也不会改变的核心信条。它回答“什么必须永远为真”。例如信任边界“业务逻辑LLM生成的内容与UI渲染按钮、回调、状态必须有清晰的、由代码控制的边界。”非功能性需求“性能优于炫技可维护性优于过度优化。”产品哲学“这个工具是为深夜赶工的程序员设计的每一个交互都必须能在半睡半醒的状态下完成。”编写L1时要像撰写法律条文一样严谨。每条都应该是一个不可妥协的断言。如果一条“原则”在项目压力下曾被打破那它可能不属于L1而是L3或L6的素材。L2 — 知识层Knowledge这是项目的“短期记忆”描述当前的真实情况。它必须是可验证、有时效性的。内容包括当前阶段“V1.0核心功能已上线正处于V1.1性能优化与监控迭代中。”已知问题“数据库连接池在高峰时段有泄漏嫌疑监控指标见/dashboard/health。”近期决策“经过POC决定用React-Query替代自制的数据获取层迁移进行中。”L2需要定期如每次发布后更新。它的作用是防止AI基于过时或错误的前提进行规划。L3 — 方法层Methods这是项目的“最佳实践手册”记录那些被验证过行之有效的工作方式。例如开发流程“功能开发遵循‘RFC - 实现 - 同行评审 - 集成测试’四步法。”代码风格“错误处理使用Result类型禁止滥用try-catch吞掉异常。”测试策略“核心算法单元测试覆盖率必须90%UI组件使用快照测试。”L3的内容来源于成功的经验是“我们是怎么做对的”的总结。L4 — 标准作业程序层SOPs这是项目的“操作手册”针对重复性任务提供 step-by-step 的配方。例如发布流程“1. 运行全量测试套件。 2. 更新CHANGELOG.md。 3. 打上Git标签。 4. 执行CI/CD流水线。”数据库迁移“使用db-migrate工具每次变更必须包含up和down脚本并在测试环境先行验证。”SOPs的目标是减少认知负荷确保重复性工作的一致性和可靠性。L5 — 思维模式层Thinking Modes这是最抽象但也最强大的一层。它定义了在面对不同任务时应该启动怎样的“思考姿势”。例如证据优先模式“当评估一个性能问题时首先查看监控图表和日志而非直接猜测。”辩证模式“当设计一个新API时必须同时构思至少两种对立方案并列出各自的优劣。”安全门模式“任何涉及用户数据或外部调用的代码变更必须经过‘可能发生的最坏情况是什么’的审查。”L5教会AI的不是“做什么”而是“如何想”。L6 — 心血方法层Heart Methods这是项目的“伤疤记忆”是最珍贵的部分。L6条目必须源自真实的、痛苦的失败教训。它不是一个励志标语集。格式通常是“我们曾以为X是个好主意因为Y但结果Z发生了所以我们现在知道必须做A。” 例如L6-1过早抽象之痛诱因在只有两个相似组件时就抽象出一个通用的“超级组件”。惨痛结果当第三个用例出现时抽象无法容纳导致大量胶水代码和难以调试的Prop钻探。教训“在出现至少三个明确、稳定的重复模式之前拒绝抽象。复制粘贴优于错误的抽象。”检测方法当提议“创建一个通用的BaseComponent”时反问“哪三个具体的组件需要它它们各自的差异点是什么”L6的力量在于其具体性和情感重量。没有真实伤疤的“经验”不配进入L6。3. 核心文件实操从“最小可行信条”开始看到六层模型你可能会觉得工程浩大。但Project Doctrine的精髓恰恰是反对“大而全”的文档债务。它推崇的是MVPMinimum Viable Product思路即“最小可行信条”Minimum Viable Doctrine, MVD。一个有用的Doctrine可以在30分钟内创建仅包含4个文件state-snapshot.md状态快照内容用一段话描述项目“此刻”的样子。当前版本、正在进行的核心任务、下一个里程碑、已知的最大风险。实操打开编辑器回答“如果我现在要请假一周接手的同事最需要知道哪三件事才能不让项目脱轨” 把答案写下来。注意不要写成长篇大论的项目报告。保持在一屏之内聚焦于“现在”和“近未来”。layer-1-ideology.mdL1 意识形态内容写下3条你认为这个项目绝不可动摇的核心原则。实操回顾你做过的所有技术决策哪个决策你最为坚持即使被人挑战也不会退让把它提炼成一句话。例如“数据流必须单向状态变更必须有迹可循。”心得L1条目不宜过多3-5条足矣。每一条都应该像物理定律一样坚实。如果你写了一条但想到“嗯……特殊情况也许可以例外”那就删掉它。failure-memory.md失败记忆内容记录3个你们或你犯过的、不希望AI重蹈覆辙的经典错误。实操模板### FM-[编号]: [错误名称] - **诱惑**当时为什么觉得这个做法很合理例如“让LLM直接输出JSON Schema来驱动表单看起来既动态又强大。” - **如何失败的**具体出了什么问题例如“Schema轻微变动导致前端解析崩溃错误信息难以调试回退成本极高。” - **未来如何检测**什么迹象表明这个错误可能再次发生例如“任何计划中让非确定性模型LLM的输出直接成为确定性运行时前端/后端的结构化输入。” - **正确做法**现在我们知道应该怎么做例如“LLM输出纯文本描述由固定的、经过测试的转换函数将其映射为确定的Schema。”核心失败记忆不是问责而是免疫。重点在于“诱惑”——那个错误当时看起来多么正确。这能帮助AI识别类似的“糖衣炮弹”。bootstrap-prompt.md引导提示内容一段给AI的“开场白”告诉它如何加载并使用这个Doctrine。实操示例你正在进入 [项目名] 项目。请先阅读本项目的 Doctrine 以理解其工作方式。 核心文件是 1. state-snapshot.md了解我们当前在哪。 2. layer-1-ideology.md理解我们必须遵守的核心原则。 3. failure-memory.md避免我们曾经犯过的昂贵错误。 在开始任何实质性工作前请先回答“学徒检查”中的问题以证明你已理解上下文。使用将这个提示词放在你的AI运行时配置中如Claude Code的.claude/skills/或项目的AGENTS.md文件里。创建完这4个文件你的MVD就完成了。接下来只需要在你的AI助手启动时加入一句指令“请先阅读项目Doctrine。” 你会发现对话的起点和质量将截然不同。4. 进阶实践让Doctrine融入开发生命周期MVD只是一个开始。随着项目推进Doctrine应该像一个活文档一样生长和演化。关键在于建立轻量级的维护习惯避免让它成为负担。4.1 日常使用场景在正确的时间点触发你不必每天“维护”Doctrine。而是在几个关键决策点让它介入新会话开始时这是黄金法则。任何新的AI协作会话第一指令都应该是“请先阅读项目Doctrine”。这设定了正确的思考基调。制定重大计划前当你要开始一个涉及架构变更或新模块开发的大任务时让AI基于Doctrine尤其是L1和L6来评估初步方案。评审代码或方案时用Doctrine作为客观的评审标准。问“这个PR是否符合L3中的代码风格有没有触犯L6里的某个教训”同一个错误出现第二次时这是一个强烈的信号表明某个教训需要被固化。立即将其整理成一条新的failure-memory条目。达成重要里程碑后在版本发布或项目阶段完成后花15分钟回顾更新state-snapshot.md并思考是否有新的经验可以晋升为L3方法或L6教训。对于拼写错误修正、格式化等琐事则完全不需要动用Doctrine。4.2 内容维护与精炼避免文档腐败Doctrine最大的敌人是“内容膨胀”和“过时”。必须建立严格的“晋升路径”和“清理机制”。原始记录 - 叙事日志 - 决策记录 - 信条条目原始记录散落在聊天记录、评论、临时笔记中的碎片想法。叙事日志在一个独立文件如references/narrative-log.md中用段落形式记录一个完整决策的来龙去脉。“我们遇到了X问题考虑了A、B方案因为Y原因选择了B结果Z。”决策记录如果这个决策具有长期影响将其提炼为简短的决策记录references/decision-records/DR-001.md说明问题、选项、决定及理由。信条条目只有那些具有普适性判断价值的经验才够格进入正式的Doctrine层如L3、L6。例如从“我们这次选了B方案”晋升为“本项目中在X类问题下应优先考虑B类方案因为……”。定期检视与分类 每隔一个迭代周期如一个月快速浏览Doctrine的所有条目对每个条目做出四选一的裁决保留依然有效无需改动。晋升某个临时记录如Handoff里的一个观察已被多次验证可提炼为正式方法或教训。归档条目已过时但具有历史参考价值。移动到archive/目录并标记上下文。删除条目已失效、重复或模糊。直接删除Git历史会保存它。核心原则一个健康的Doctrine应该随着时间推移变得更小、更锋利而不是更大、更臃肿。它的价值在于密度而非体积。4.3 三种应用模式的选择Project Doctrine设计了三种模式以适应不同的协作场景独奏模式适合个人开发者或小团队主程。Doctrine是你的“外接记忆”风格可以个人化更新自由。重点是捕捉你个人与AI协作中形成的模式。团队模式适合多人多AI协作的项目。Doctrine是团队的“判断契约”。需要简单的治理如通过PR更新并且failure-memory必须去个人化描述“项目”犯的错而非“某人”犯的错。通常会额外需要governance.md定义如何更新Doctrine和decision-records.md记录重大决策。考古模式当你接手一个外部项目开源项目、遗留系统时使用。你不是在“制定”信条而是在“挖掘”信条。通过分析项目的PR、Issue、代码审查记录来推断其潜在的L1原则和L6教训。重要考古模式的产出是“贡献假设”而非官方规则。每条推断都应附带置信度和证据来源目的是减少沟通成本而不是操纵维护者。如何选择绝大多数个人项目从独奏模式开始即可。只有当项目需要多人共同维护其“判断一致性”时才升级到团队模式。考古模式则是一个强大的入职工具能让你快速理解一个成熟项目的“潜规则”。5. 避坑指南与常见问题在实际引入Doctrine的过程中你会遇到一些典型的困惑和陷阱。以下是我从多次实践中总结出的经验。5.1 误区一把Doctrine写成另一份架构文档症状layer-1-ideology.md里写满了“使用微服务架构”、“前后端分离”、“采用RESTful API设计”。问题这些是技术选型或架构决策不是“意识形态”。它们可能会随着技术演进而改变。修正追问“为什么”。为什么用微服务可能是为了“独立部署和扩展”。那么L1条目应该是“核心业务能力必须封装为可独立部署、扩展和失败的单元。” 这才是不会随技术潮流改变的核心信念。5.2 误区二L6条目空洞无物像鸡汤症状layer-6-heart-methods.md里写着“保持代码简洁”、“注重用户体验”、“团队沟通很重要”。问题这些是正确但无用的废话。没有具体的失败场景就无法指导具体行动。修正为每一条L6强制关联一个具体的、痛苦的失败故事。例如坏的L6“保持代码简洁。”好的L6“警惕‘聪明’的代码。我们曾为了减少10行代码引入了一个递归泛型解析器导致新成员一周都无法理解一个简单数据流。现在约定可读性永远高于炫技性简洁。任何让资深开发者停顿超过一分钟去理解的代码都必须重写并附上解释性注释。”5.3 误区三过度依赖扼杀创造性症状每个微小的决策都要求AI“查一下Doctrine”导致效率低下AI也不敢提出突破性的新方案。问题Doctrine是护栏不是镣铐。它的作用是防止重复踩坑而不是禁止探索新路。修正明确Doctrine的适用范围。在bootstrap-prompt.md中说明“Doctrine是我们的经验护栏。在已知模式内请严格遵守。当探索全新领域时可以提出突破现有信条的方案但必须明确指出突破点并论证其必要性与风险控制措施。”5.4 常见问题速查表问题可能原因解决方案AI似乎忽略了Doctrine引导提示词不够明确或未集成到运行时。1. 确保bootstrap-prompt.md内容直接、无歧义。2. 检查是否将其正确配置到AI的上下文加载路径如Claude Code的.claude/skills/目录。3. 在新会话中手动输入第一条指令“请先完整阅读docs/skills/our-project-doctrine/下的所有文件并总结我们的三个核心禁忌。”Doctrine文件太多维护麻烦试图一次性创建完整的六层或记录了太多琐事。回归MVD4个文件。坚持“只有缺失它让你感到痛苦时才创建新文件或条目”的原则。使用references/incubation.md作为草稿本定期如每月评审晋升。团队对Doctrine条目有争议在团队模式下不同成员对“教训”或“原则”理解不同。1. 建立轻量治理任何Doctrine更新需发起PR并必须附上决策记录链接或具体案例。2. 争议本身可能是提炼更好原则的机会。将争议点记录为decision-records经过一段时间的实践后再回顾形成共识。考古模式推断的信条不被项目接受推断是基于个人解读可能与维护者的真实意图不符。考古模式的产出是假设。在首次提交PR时可以委婉验证“我注意到项目中有不少模式X我推断这可能是一个偏好。我这次的实现采用了X不知是否符合项目的惯例” 将推断作为沟通的起点而非真理。5.5 一个关键的实操技巧学徒检查这是检验Doctrine是否生效的“试金石”。在apprenticeship-check.md文件中设计一组问题要求AI在开始工作前回答。例如当前状态根据state-snapshot.md我们目前正处于哪个开发阶段最大的技术债是什么核心禁忌列出两条来自failure-memory.md的、我们在UI层绝对要避免的错误。判断练习如果我提议“为了快速上线让后端API直接返回渲染好的HTML片段”根据L1和L6你会如何回应最小安全步骤对于“优化首页加载速度”这个任务根据我们的方法层L3第一步应该是什么如果AI能流畅、准确地回答这些问题说明它已经成功“入学”可以用项目的思维方式来协作了。如果答案含糊或错误说明Doctrine的编写或引导方式需要调整。从我自己的经验来看引入Project Doctrine最大的转变不是AI突然变聪明了而是协作的摩擦成本显著降低了。我不再需要反复解释“我们项目的做事方式”而是可以说“去看看我们的信条。” 它就像为新加入的、记忆力只有一次会话的资深工程师准备了一份高度浓缩的入职培训手册。这份手册不教语法不教API只教这个项目独一无二的“灵魂”。当你和你的AI助手共享同一个灵魂时生产力的提升是水到渠成的事。