1. 项目概述什么是 Project Doctrine如果你和我一样长期与 AI 代理比如 Claude Code、Cursor、Codex 等协作开发项目一定遇到过这个令人头疼的场景昨天你和代理花了整整一下午通过反复试错和讨论终于敲定了一个核心架构决策——比如“所有 UI 状态必须由确定性运行时代码管理LLM 只负责生成语义块”。今天你开一个新会话满怀信心地告诉代理“继续昨天的项目。”结果它转头就给你提了一个方案把按钮的回调逻辑直接塞进了 LLM 的提示词里。那一刻你仿佛听到昨天那个下午“啪”的一声消失了。这就是典型的“手递手”交接的局限。它告诉代理“发生了什么”和“接下来做什么”但它无法传递“为什么要这么做”以及“如何判断什么是对的”。你的项目在成长中积累的那些宝贵的、用时间和错误换来的“项目直觉”或“团队共识”在每次会话重启时都被重置了。Project Doctrine就是为了解决这个问题而生的。它不是另一份架构文档也不是会议纪要。你可以把它理解为一个项目的“判断力传承系统”或“项目学派养成手册”。它的核心目标非常明确将项目中那些来之不易的经验、教训、品味和决策逻辑转化为一种可被 AI 代理持续理解和运用的“上下文”。简单说它教 AI 用你的方式思考用项目的标准判断。想象一下你为项目培养了一位永不离职、且能瞬间理解项目所有历史背景和潜规则的“资深成员”。这就是 Doctrine 要达成的状态。它通过一套结构化的文件体系一个“技能”包捕获从核心意识形态到具体失败案例的一切确保项目的判断连续性而不仅仅是工作连续性。2. 核心理念与价值为什么“手递手”远远不够在深入具体操作前我们必须先统一思想为什么现有的“手递手”模式会失效理解了这一点你才能明白 Doctrine 每个设计背后的深意。2.1 “手递手”的天然缺陷“手递手”文档通常回答三个问题What happened?刚才发生了什么What changed?代码/状态有什么变化What‘s next?接下来该做什么这很好对于延续一个具体的、短期的任务链足够了。但它天然缺失了另外三个维度的信息Why was this chosen?当初为什么选这个方案另一个看似合理的方案为什么被毙了What looks good but is actually bad?哪些做法看起来聪明实则是陷阱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。示例“生产环境热修复 SOP1. 从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可能是你最先能写出干货的文件。它系统化地记录那些“看起来合理实则有毒”的决策。标准结构诱惑那个错误方案当时为什么看起来有吸引力例如“让 LLM 直接生成 HTML 按钮代码看起来能快速实现动态 UI。”如何失败具体是怎么搞砸的例如“导致 UI 行为不可预测无障碍属性缺失且与前端框架状态管理冲突难以调试。”未来如何检测以后怎么提前嗅到这个陷阱的味道例如“任何计划中如果 LLM 的输出直接变成了可执行的 UI 组件、回调函数名或状态标识符。”正确做法应该怎么做例如“LLM 输出结构化的意图描述如{action: confirm, target: item_123}由前端的确定性渲染器将其转换为具体的 UI 元素和事件绑定。”实操心得撰写失败记忆时心态要像科学家记录实验失败而不是法官宣判。目的是形成“免疫记忆”而不是追责。好的失败记忆条目能让代理在提出类似方案时自己就产生“警觉”。4.2 品味示例展示“好”与“不够好”的对比taste-examples.md用具体的、对比的案例来定义抽象的“项目品味”。形容词是苍白的对比是强大的。标准结构场景简要描述一个设计或决策点。不够好展示一个符合通用标准但不符合本项目品味的方案并解释其缺点。好展示本项目认可的方案并解释其优点。为何“好”胜出从项目核心价值如可维护性、用户体验一致性、性能角度深入分析。示例场景处理用户删除操作的确认。不够好代理在对话中说“要我帮你删除这个文件吗”这创造了“对话剧场”但未触发任何实际的、可撤销的确认流程。好UI 呈现一个标准的确认对话框标题为“删除文件”并带有“取消”和“永久删除”两个按钮删除操作记录在审计日志中。为何“好”胜出后者提供了可预测的、可访问的、且具备安全边界的产品行为符合 L1 中“用户操作必须明确且可追溯”的原则。4.3 学徒检验验证代理是否“入门”apprenticeship-check.md是一组问题用于在新代理会话开始时检验它是否真正消化了 Doctrine 的精髓而不是仅仅“读过”了文件。典型问题根据当前状态L2我们现在处于项目的哪个阶段当前最大的障碍是什么根据意识形态L1如果有一个功能请求要求快速但破坏解耦我们应该如何回应请回忆一个失败记忆FM中的例子并说明如果遇到类似诱惑你会如何避免。针对“为用户添加一个反馈按钮”这个任务你会启动哪种思维模式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 第一步准备技能模板获取模板克隆或下载fagemx/project-doctrine仓库。放置技能根据你使用的 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中引用它。重命名将技能目录名中的your-project替换为你实际的项目名称。5.2 第二步填充核心四文件30分钟挑战不要试图一次性填满所有文件。集中精力完成以下四个就能立刻获得 80% 的收益。state-snapshot.md(5分钟)回答“我们现在在哪”当前版本/分支。刚刚完成的主要工作。接下来 1-2 天要解决的头号问题。已知的、最令人头疼的技术债或 Bug。写法用项目日志或待办事项列表的口吻简洁列出事实。layer-1-ideology.md(10分钟)回答“我们绝不妥协的是什么”写下3条你最核心、最不容挑战的项目原则。例如“数据层必须完全独立于 UI 框架。”“所有用户输入必须在首次接触时进行验证和清理。”“错误信息必须对用户友好同时对开发者可调试。”写法每条原则用一句话阐明可以加一句简短的理由。failure-memory.md(10分钟)回答“我们别再掉进那个坑了”写下3个你或你的代理最近犯过的、让你捶胸顿足的错误。为每个错误套用“诱惑 - 失败 - 检测 - 正确做法”的结构。写法描述要具体像在写一个事故复盘报告。bootstrap-prompt.md(5分钟)创建一键启动提示词。参考上文示例修改项目名和路径。将其设置为你的 AI 开发工具的默认会话开场白。5.3 第三步集成与测试集成在你的 AI 代理配置中确保它能读取到你放置的技能目录。首次测试开启一个全新的代理会话使用你的bootstrap-prompt.md。验证向代理提问检验它是否理解了状态快照、是否记住了那三条核心原则、是否能复述一个失败记忆。如果它答得上你的 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协作 - 是 - 【选择个人模式】 - 是 - 和多人/多代理协作 - 是 - 【选择团队模式】 - 否 - 你要参与一个已有项目 - 是 - 【选择考古模式】 - 否 - 项目很小或一次性 - 是 - 【暂不需要DoctrineREADME足够】7. 日常使用与维护让 Doctrine 保持活力Doctrine 不是创建完就束之高阁的文档。它需要被使用也需要被维护否则就会变成另一份过时的“祖传代码”。7.1 何时使用 Doctrine在以下五个关键时刻养成习惯去“咨询” Doctrine开启新会话时这是强制动作。使用bootstrap-prompt让代理加载上下文。规划大型任务前在脑暴或编写详细计划前快速浏览 L1意识形态和 L6核心方法确保方向不偏。评审设计方案时用 Doctrine 作为评审清单。这个方案有没有触犯失败记忆里的禁忌是否符合我们的品味示例同一个错误第二次出现时立即停下来将这次事件整理成一个新的失败记忆条目。达成重大里程碑后在发布新版本或完成一个重要阶段后更新state-snapshot.md并回顾是否有新的经验可以提炼到 L3方法或 L6核心方法中。什么时候可以不用修改错别字、格式化代码、查找简单的 API 用法时不需要惊动 Doctrine。7.2 如何维护与更新Doctrine 应该像代码一样被维护遵循“小而精而非大而全”的原则。建立一个轻量级的维护流程定期回顾设定一个节奏如每两周或每个冲刺周期结束花 15 分钟快速浏览 Doctrine。信息分拣当发生重要事情时判断其归属保留信息仍然有效无需改动。晋升一次性的“手递手”观察被证明具有普遍价值将其提炼为正式的失败记忆、品味示例或 L6 条目。归档信息已过时如旧版本的状态但仍有历史参考价值。将其移至references/archive/目录并注明失效日期。删除信息重复、错误或不再有任何判断价值。直接删除Git 历史会保存记录。孵化区创建一个references/incubation.md文件。对于不确定是否要放入正式 Doctrine 的观察或想法先扔到这里。在定期回顾时再决定其命运。核心原则Doctrine 应该随着时间的推移变得更小、更锋利而不是更庞大、更笨重。不断合并、提炼、删除过时的内容确保每一条都像手术刀一样精准有用。实操心得维护 Doctrine 最大的敌人是“完美主义”和“拖延症”。不要想着一次性把它修得完美。采用“增量更新”和“及时止损”策略。每次会话后如果有一个强烈的“啊哈”或“哎呀”时刻花 2 分钟把它记下来。积累的力量远大于一次性的宏大工程。8. 常见问题与疑难解答在实际应用 Project Doctrine 的过程中你可能会遇到一些典型问题。以下是我根据经验整理的排查清单。问题现象可能原因解决方案代理似乎完全忽略了 Doctrine1. 技能路径配置错误。2. 引导提示词未生效。3. 文件格式或语法错误导致代理无法解析。1. 检查技能目录是否放在代理运行时指定的正确路径如.claude/skills/。2. 手动在会话中粘贴bootstrap-prompt.md的内容看代理是否有反应。3. 检查 Markdown 文件是否有严重格式错误尝试简化文件内容进行测试。代理读了但理解肤浅仍提出违反原则的方案1. Doctrine 条目写得太模糊、抽象。2. 缺乏具体的“失败记忆”或“品味示例”作为反面教材。3. 条目太多重点被稀释。1. 重写模糊条目。使用“必须/禁止”等绝对化语言并补充具体原因。2. 为关键原则补充 1-2 个failure-memory.md条目用故事加深印象。3. 进行“ Doctrine 大扫除”删除或合并非核心条目确保 L1 不超过 5 条。维护 Doctrine 成了负担更新不及时1. 一开始写得太多太细。2. 更新流程太复杂。3. 感觉不到即时收益。1.回归 MVD。只保留当前真正在发挥作用的条目清空其他。2.简化流程。在个人模式下允许自己直接快速编辑。团队模式下设立简单的 PR 模板。3.聚焦痛点。只记录那些让你“疼”过一次以上的事情。当代理因 Doctrine 避免了一个错误时你能立刻感受到价值。团队中对某条 Doctrine 有争议这是健康的现象说明 Doctrine 触及了真正的决策点。1. 将争议点记录到references/incubation.md或decision-records.md。2. 安排一次简短的讨论聚焦于具体的失败案例或可观测的结果而不是个人偏好。3. 根据讨论结果更新、修订或删除该条目。Doctrine 应是活共识不是死规矩。考古模式下的推断置信度很低项目历史杂乱或决策记录不透明。1.调整目标从推导“为什么”转为记录“是什么”。多记录观察到的代码模式、PR 评论中的高频词汇。2.聚焦近期古老的历史可能已不适用。重点关注最近 6-12 个月的活跃分支和合并记录。3.提出试探性 PR有时一个精心设计但略有出入的 PR 所收到的审查意见是最高质量的信源能快速验证你的推断。Doctrine 文件应该放在 Git 仓库里吗取决于内容敏感性。默认推荐放在仓库内如docs/project-doctrine/因为判断逻辑是项目资产的一部分。如果涉及敏感信息如内部流程、未公开的商业逻辑可以放在私有仓库或通过.gitignore排除。对于考古模式产出的推断建议放在个人本地不作为 PR 的一部分提交。最后记住 Project Doctrine 的终极心法它不是用来总结项目的而是用来萃取项目的“学派”的。你的目标不是创建一份无所不包的百科全书而是锻造一把锋利的、能传承判断力的钥匙。从最小可行版本开始让它与你和你代理的协作共同进化你会发现自己花在纠正方向、重复解释上的时间越来越少而用于创造价值的精力越来越多。这正是高效协作的本来面目。