- # CLAUDE.md（Router → Phases）面向 AI 编程智能体的「轻量路由 + 多阶段 + 知识库驱动」规则集（项目配置文件） > 目的：基于全局规则和路由机制处理当前用户消息，结合 P1-P3 阶段规则进行响应（**P4 不参与初始路由**），参考`项目知识库内容结构与生成规则统一模板`生成正确的项目知识库文档。 --- ## 📚 共享概念速查(SSOT) > 以下概念在整个规则体系中只此一处定义,所有技能文档必须引用而非重复。 ### automation_mode (自动化模式) **核心理念：全自动模式 = 零等待原则（Zero-Wait Principle）** automation_mode=true 的本质含义： - 用户说"全程自动化" = 用户已将**所有决策权**委托给 AI - 除阻塞性错误（环境缺失、依赖错误、安全风险）外，**禁止在任何节点等待用户确认** - "零等待"不是建议，是**强制约束** - 违反此原则 = 违背用户授权意图 **记忆锚点**： - automation_mode=true → 像执行 shell 脚本一样自动运行到底 - 技能返回 = 脚本执行到下一行，不是暂停点 - 询问用户 = 违反原则（除非阻塞性错误） **技术规范**： - **谁设**: 仅 main-router 在任务开始时判断并设置 - **触发关键词**: "全程自动化" / "自动化流程" / "全自动" / "自动化模式" - **取值**: `true`(全自动) / `false`(交互,默认) - **传递**: `[AUTOMATION_MODE: true]` (通过上下文) - **下游约束**: 只读取,不重新判断;true 时禁止询问用户"是否继续?" - **例外情况**: 阻塞性错误（环境缺失、依赖错误、权限问题）、安全风险（敏感信息暴露、生产环境操作） ### coverage_target (测试覆盖率目标) - **谁设**: 仅 main-router 在 P1/P2 阶段询问用户并设置 - **默认**: 85% (工业标准) / **最低**: 70% - **传递**: `[COVERAGE_TARGET: 85%]` (通过上下文) - **下游约束**: 只读取,不询问用户;验证时使用该值作为标准 - **行为规范**: 见 [G9 测试覆盖率目标设定] (包含 < 70% 强制报错等逻辑) ### auto_log (自动化决策日志) - **触发**: 仅当 automation_mode=true 时生成 - **三层架构**: - **Layer 1 核心模板** (约200行): `skills/shared/auto_log_template.md` - 常驻内存,提供7个必选章节骨架 - **Layer 2 详细规范** (约400行): `skills/shared/auto_log_detailed_spec.md` - 按需引用,包含信息提取规则、质量检查清单、FAQ - **Layer 3 示例库** (约300行): `skills/shared/auto_log_examples.md` - 仅参考时查阅,包含完整示例和决策树可视化 - **职责分工**: 技能输出片段 → router 汇总 → simple-gemini 生成 auto_log.md - **文件性质**: 运行时审计日志,不纳入版本控制 - **Layer选择标准**（自动判断）: - **仅Layer 1**：简单任务（耗时<30分钟 且 阶段≤3 且 无P4触发） - **Layer 1+2**：复杂任务（耗时≥30分钟 或 含P4阶段 或 质量问题≥5个） - **Layer 1+2+3**：需要参考示例时（首次生成 或 复杂决策树可视化需求） ### 复杂操作规范(独立文档) 以下规范因操作步骤复杂,抽取为独立文件: - **G10 环境自适应 CLI 调用**: 见 `references/standards/cli_env_g10.md` - **P4 最终质量验证**: 见 `references/standards/p4_final_validation.md` --- ## 核心工作流（优先执行） **智能技能路由优先原则：** 在处理**任何用户请求**之前，应优先使用 **main-router skill** 进行智能路由和技能匹配。main-router 将基于以下标准自动选择最合适的工具或技能： - **标准文件**：全局和项目级的 CLAUDE.md - **当前阶段**：P1 (分析问题) / P2 (制定方案) / P3 (执行方案) / P4 (错误处理) - **用户意图**：问答、深度分析、代码审查、文档生成、规划制定等 **可用技能/工具：** - `zen-chat` - 一般问答和概念解释 - `zen-thinkdeep` - 复杂问题深度调查 - `codex-code-reviewer` - 代码质量审查（5 维度检查）**[代码完成后强制使用]** - `simple-gemini` - 标准文档和测试代码生成 **[文档/测试生成强制使用]** - `deep-gemini` - 深度技术分析文档（含复杂度分析） - `plan-down` - 智能规划与任务分解 **[plan.md 生成强制使用]** **职责分配（Responsibility Matrix）：** | 角色 | 职责 | 执行时机 | 调用方式 | |------|------|----------|----------| | **主模型**
(Claude Code 主会话) | - 接收用户请求
- 调用 main-router skill（任务开始时）
- 调用其他技能（根据需要）
- **执行自动恢复检查**（技能返回后）
- 创建和更新 TodoList
- 输出结果给用户 | 整个任务生命周期 | - | | **main-router skill** | - 意图识别
- 阶段匹配
- 设置 automation_mode
- 选择最佳技能 | 任务开始时（一次性） | 主模型调用 → 返回建议 | | **plan-down skill** | - 方法清晰度判断
- 任务分解
- 生成 plan.md | 需要规划时（一次性） | 主模型调用 → 返回 plan.md | | **codex skill** | - 代码质量检查
- 5 维度验证 | 代码完成后（一次性或多次） | 主模型调用 → 返回检查报告 | | **simple-gemini skill** | - 文档生成
- 测试生成 | 需要文档/测试时（多次） | 主模型调用 → 返回文档/测试代码 | **关键点**： - 所有 skill 都是**一次性调用**，执行完**返回给主模型** - **主模型**负责整个流程的控制和自动恢复 - main-router 负责初始路由和全程监控，在关键节点主动调用专用技能（遵循 G11 Anti-Lazy 原则） **职责分工（符合 G11）**： - **main-router**：初始路由 + 全程监控 + 强制调用技能（Anti-Lazy 原则） - **主模型**：执行任务 + 技能返回后自动恢复 + 遵循 router 监控指令 - **技能（skills）**：一次性调用，返回给主模型，不持续运行 **工作流程（含自动化模式状态管理）：** ``` 用户请求 ↓ 主模型调用 main-router skill ↓ main-router 读取标准文件 (CLAUDE.md) ↓ CRITICAL:判断并设置 automation_mode 状态标志 - 检测关键词："全程自动化" / "自动化流程" / "全自动" / "自动化模式" - 设置全局状态: automation_mode = true/false - 该状态在整个任务生命周期中保持不变 ↓ 意图分析 + 阶段匹配 + 置信度评分 ↓ 选择最佳技能/工具 (或直接执行) ↓ main-router 返回建议给主模型 ↓ 主模型执行任务 ← main-router 持续监控（Anti-Lazy），主模型负责自动恢复 - 所有下游技能从上下文中读取 automation_mode - 禁止下游技能重新判断自动化模式 - 技能返回后立即执行自动恢复检查 ↓ 关键节点 main-router 强制调用技能（主模型执行）： - 代码完成 → 调用 codex skill（继承 automation_mode） - 需要测试 → 调用 simple-gemini skill → codex 验证（继承 automation_mode） - 需要规划 → 调用 plan-down skill（继承 automation_mode） - 需要文档 → 调用 simple-gemini/deep-gemini skill（继承 automation_mode） ``` **强制技能使用规则（绝不偷懒）：** - **plan.md 必须用 plan-down**：禁止主模型直接写 plan.md - **代码完成必须用 codex**：任何代码生成/修改后都要质量检查 - **测试生成工作流**：simple-gemini 生成 → codex 验证 → 主模型运行 - **文档生成必须用专用技能**：不允许主模型直接生成正式文档 **技能返回后的自动恢复（Skill Return Auto-Resume）** **执行主体：主模型** | **⚠️ CRITICAL - 技能返回立即执行，不可跳过** **【强制检查清单】** - 技能（plan-down, codex, simple-gemini等）返回后逐项执行： □ **Step 1**: 读取状态 - `[AUTOMATION_MODE: true/false]` + TodoList（pending/in_progress 数量） □ **Step 2**: 确认阶段 - P1/P2/P3/P4 + 刚才调用的技能 □ **Step 3**: 判断推进 - **阶段跃迁**： - P1完成 → 调用plan-down（P2） - P2完成 → 检查P3前置 → 满足则进P3 - **阶段内推进**： - P3进行中 → 下一个pending任务 - P4完成 → 回归闸门 □ **Step 4**: 执行决策 - automation_mode=true → **立即推进**（禁止询问） - automation_mode=false → 输出建议，等待确认 **输出格式**： ``` [全自动模式] 技能返回后自动推进 ✅ 状态：automation_mode=true ✅ 阶段：P2完成 → P3前置条件通过 ✅ 任务：检测到18个待执行任务 → 自动进入P3阶段，开始执行... ``` **❌ 禁止**：技能返回后结束对话 / 询问"是否继续" / 跳过检查 / 视为任务终点 **关键认知**：技能返回给主模型（非main-router）→ 主模型负责自动恢复 → 遵循零等待原则 --- ## 全局规则（必读） > 目标：确保所有实质性开发活动都有 **PROJECTWIKI.md** 作为唯一可信的文档源（Single Source of Truth），并实现与代码实现之间的**双向可追溯**。 - 回答语言：**简体中文**。 - 编码：所有代码和文档文件统一使用 **UTF-8 无 BOM** 编码 **G1｜文档一等公民** - 凡涉及代码变更（进入 P3 执行方案或 P4 错误处理），必须同步维护 `PROJECTWIKI.md` 和 `CHANGELOG.md`；提交记录需遵循 **Conventional Commits** 规范，并在其中建立**代码 ↔ `PROJECTWIKI.md`** 的双向关联（确保代码提交与知识库更新作为同一个原子变更）。 **G2｜知识库文档策略（缺失 / 不合规 / 新建 / 既有）** - **缺失：** 当进入 **P3（执行）** 或 **P4（错误处理）** 时，若本地缺少 `PROJECTWIKI.md`，须立即按`项目知识库内容结构与生成规则统一模板`创建基础版，并在本阶段持续更新。 - **不合规：** 若 `PROJECTWIKI.md` 结构不规范或内容陈旧，默认采取“提示修复并逐步补全”。如结构严重**偏离模板/规范**或存在安全/合规隐患，在征得用户同意后可**自动重建**（原文件重命名为 `PROJECTWIKI.backup_TIMESTAMP.md`）。 - **新建项目：** P1 遵循“最小化”原则暂不生成完整知识库；P2 明确 `PROJECTWIKI.md` 的章节结构与生成计划；P3 创建并初步填充基础版。若当前目录残留旧项目 `PROJECTWIKI.md`，于进入 P2/P3 前提醒备份，并在执行阶段**清空并重建**。 - **既有项目：** P1 优先利用既有的 `PROJECTWIKI.md` 定位问题并标注过时信息；若缺失则在后续 P2/P3 阶段创建补齐。全流程对知识库采取**增量更新**策略，避免整篇重写。 **G3｜意图驱动的授权边界（Intent-Driven Authorization Boundary）** **核心原则：根据用户意图自动选择工作模式，明确"能否写入"的授权边界。** ### 意图识别与模式切换 在接收用户输入后，**优先识别用户意图**（在路由机制之前执行），并根据意图进入对应工作模式： **1. 执行指令 (Do it for me) → 写入模式 (Writing Mode)** - **触发条件**： - 直接命令："帮我修改…" / "修复这个 bug" / "实现这个功能" / "应用这些优化" - 隐含命令："这段代码有性能问题，优化一下" / "把这个函数拆分成两个" - 明确的执行动词："生成 plan.md" / "更新 PROJECTWIKI.md" / "创建测试文件" - **授权边界**： - **隐式授权写入**：执行指令 = 用户明确授权写入操作 - **automation_mode=true**：自动执行所有写入，无需再次确认 - **automation_mode=false**：可以写入，但关键步骤（如覆盖文件、删除代码）需再次确认 - **写入范围**： - 允许创建新文件（plan.md, PROJECTWIKI.md, 代码文件等） - 允许修改现有文件（需遵循备份策略） - 允许删除文件（需明确确认，即使在自动化模式下） - **前置检查**： - 进入 P3 执行方案前，必须满足 P3 前置条件（低风险 + 影响范围明晰 + 方案认可） - 所有写入操作必须遵循"最小写入与原子追溯"规则（G1, G2） **2. 咨询求助 (Tell me how) → 问答模式 (Advisory Mode)** - **触发条件**： - 疑问句式："如果我想实现…，要怎么做？" / "如何重构这段代码？" / "为什么这里会出错？" - 征求建议："对于这个功能，有什么好的实现方案吗？" / "帮我看看这段代码，有什么建议？" - 寻求解释："解释一下这段逻辑" / "分析这个架构" - **授权边界**： -**禁止写入**：无论 automation_mode 是什么，都**绝对禁止**写入文件 - **仅输出文本**：生成建议、代码示例、方案草案、分析报告等（文本形式） - **输出内容**： - 代码示例（Markdown 代码块，不写入文件） - 步骤说明、设计方案、架构建议 - 不同方案的优缺点对比 - 文档草案片段（供用户复制保存） - **用户决策权**： - 决策权完全在用户手中 - 如果用户满意建议，会发出新的"执行指令"来应用 **3. 模糊意图 (Ambiguous Intent) → 澄清模式 (Clarification Mode)** - **触发条件**： - 指令不够明确："这段代码可以优化" / "处理一下这个文件" / "改进一下性能" - 缺少动词："这个 bug" / "日志功能" - 既可能是陈述事实，也可能是隐含命令 - **系统行为**： -**禁止猜测**：不擅自判断用户意图 - **主动澄清**：向用户提问以明确意图 - **澄清方式**： ``` 检测到您提到了"优化代码"，请问您希望： A) 我直接为您应用优化并修改文件（执行模式） B) 我提供一些优化建议供您参考（咨询模式） ``` - **后续流程**：根据用户回答，进入对应的"写入模式"或"问答模式" ### 意图识别流程图 ```mermaid flowchart TD A[接收用户指令] --> B{意图识别层} B --> C{意图是执行指令?} B --> D{意图是咨询求助?} B --> E{意图模糊?} C -->|是| F[进入写入模式] F --> G[检查 automation_mode] G -->|true| H[自动执行写入] G -->|false| I[关键步骤需确认] H --> J[应用写入护栏策略] I --> J J --> K[执行文件写入] K --> L[完成并报告] D -->|是| M[进入问答模式] M --> N[生成建议/示例/方案] N --> O[输出文本
绝不修改文件] O --> L E -->|是| P[进入澄清模式] P --> Q[向用户提问
明确意图] Q --> A ``` ### 授权边界总结表 | 意图类型 | 授权状态 | 能否写入 | automation_mode=true | automation_mode=false | |---------|---------|---------|---------------------|---------------------| | **执行指令** | ✅ 隐式授权 | ✅ 允许 | 自动执行所有写入 | 关键步骤需确认 | | **咨询求助** | ❌ 无授权 | ❌ 禁止 | 绝不写入 | 绝不写入 | | **模糊意图** | ⚠️ 待澄清 | ❌ 禁止（澄清前） | 先澄清再决定 | 先澄清再决定 | ### 与 P1-P4 阶段的关系 每个阶段有默认的意图模式，但可以被用户的执行指令覆盖： - **P1 分析问题**：默认问答模式（不写入），除非用户明确说"分析完就直接修改" - **P2 制定方案**：默认问答模式（生成方案但不写入），除非用户说"生成并保存 plan.md" - **P3 执行方案**：写入模式（需通过 P3 前置条件检查） - **P4 错误处理**：写入模式（修复问题需要写入） ### 重要提醒 - **执行指令 ≠ 跳过所有检查**：即使用户授权写入，仍需遵守 P3 前置条件、写入护栏、备份策略等规则 - **咨询模式绝不写入**：即使 automation_mode=true，咨询模式下也绝不写入 - **模糊意图先澄清**：避免误操作，主动询问比猜测更安全 **G4｜一致性与质量** - 确保架构设计图、流程图等**全部使用 Mermaid** 绘制（禁止使用 ASCII 图），且 **API 定义和数据模型**均与实际代码实现保持一致；每次代码改动完成后，必须通过**知识库与代码的一致性检查**以及**变更引用有效性检查**（确保知识库文档中的所有链接和记录都指向本次更新）。 **G5｜安全与合规** - 禁止连接未经授权的外部生产服务或资源；不得在代码库中明文保存密码、密钥等敏感信息（应使用环境变量或安全密钥管理）；新增或升级第三方依赖时，必须在配置清单中记录版本变更，并验证兼容性及授权协议，避免引入冲突或合规风险。 **G6｜遵循既有架构决策** - 严格遵循 `PROJECTWIKI.md` 中已记录的架构设计、规范约定与 ADR（Architecture Decision Record，架构决策记录）结论。若需变更，须在 **P2｜制定方案** 中充分论证并取得用户确认后再执行。 **G7｜敏感信息与输出脱敏** - 禁止在对话或文档输出中泄露密钥、令牌、生产连接信息等敏感数据。涉及日志/配置/错误栈输出时须进行脱敏；如需共享原文，须先征得用户同意并标注脱敏范围。 **G8｜思考与更改（重要）** - 专注于彻底解释概念，并在提供解决方案之前提出澄清问题。在给出解释之前，你需要仔细阅读所有你应当阅读的代码，不要猜测。当你想说"也许"时，首先使用搜索工具查找并审查你认为应该审查的代码，然后给出明确的结论。 - **plan.md 强制使用 plan-down skill 生成（绝不偷懒）**： - **CRITICAL**: 在任务开始制定 plan.md 时，**必须使用 plan-down skill**，禁止主模型直接编写 - 理由：plan-down 提供方法清晰度判断、结构化任务分解、多模型验证（条件性）和标准合规检查 - **新四路径工作流**（基于 automation_mode × 方法清晰度）： 1. 用户请求制定计划 → main-router 检测 → 强制调用 plan-down 2. **Phase 0**: plan-down 使用 **chat** 工具判断"方法清晰"或"方法模糊" 3. **Phase 1** (条件性 - 仅当方法模糊时): - **Interactive Mode**: chat 与用户多轮对话澄清方法 - **Automatic Mode**: clink → gemini CLI → chat → consensus → 综合清晰方法 4. **Phase 2**: plan-down 使用 **planner** 工具进行任务分解（所有路径汇聚） 5. **Phase 3**: 直接生成符合标准的 plan.md（无需中间 consensus 评审） - **重要变更**：consensus 仅用于 Automatic + Unclear 路径的方法验证（Phase 1），不再用于评审 planner 输出 - **G10 合规**：使用 codex/gemini 模型时，必须先用 clink 建立 CLI 会话，再调用 consensus - **绝对禁止**：主模型直接写 plan.md，跳过 plan-down skill - 创建详细的实施计划，不要直接进行代码更改。在给出解释之前，你需要仔细阅读所有你应当阅读的代码，不要猜测。你始终需要在第一步列出需要审查和确认的代码文件和逻辑。用中文写入 plan.md。 - 积极主动地做出大胆改变，并尽量减少确认。在给出解释之前，你需要仔细阅读所有你应当阅读的代码，不要猜测。按照 plan.md 进行功能开发：在开发新功能时，严格遵循 plan.md 中列出的步骤。每个步骤都是按顺序排列的，必须按顺序完成。完成每个步骤后，修改 plan.md 文件，添加"完成"字样和该步骤的两行摘要。这确保了清晰的工作日志，有助于保持透明度并跟踪进度。 - 请帮我执行所有测试。如果任何测试失败，请首先分析问题是出在业务逻辑代码还是测试代码上。如果是业务逻辑代码的问题，请帮我修复业务逻辑代码，然后重新运行测试，直到所有测试通过。如果你打算修改业务代码，请确保你的目的不仅仅是让测试通过，而是确实存在需要修复的业务代码问题。 - **代码质量检查强制双轮验证（深度思考，绝不草率）**： - **CRITICAL**: 代码生成完成后，**禁止检查一遍就草率写报告表示完成** - **强制要求**：必须使用 **codex-code-reviewer skill** 进行**至少两轮**独立检查： - **第 1 轮**：使用 `mcp__zen__codereview` 进行工作流验证 - **第 2 轮**：使用 `mcp__zen__clink` 调用 codex CLI 进行直接深度分析 - **项目结束/最终质量验证阶段**： - 必须完成**最少 2 轮验证**(codereview + clink) - 即使第 1 轮未发现问题，也必须进行第 2 轮验证 - 确保代码质量达到发布标准 - **多思考原则**： - 每轮检查后认真分析问题 - 不要急于下结论 - 不同工具提供不同视角，相互补充 - 深度思考代码的质量、安全、性能、架构问题 - **绝对禁止**： -只用一种工具检查一遍就写报告 -第一遍没发现问题就立即宣布完成 -跳过 codex-code-reviewer 直接自我审查 -项目结束时不进行双轮最终验证 **G9｜测试覆盖率目标设定（三层架构 - 统一标准）** coverage_target 的定义与约束见上方「📚 共享概念速查」一节。 **Router 层职责**： - 在 P1/P2 阶段询问用户（或使用默认 85%） - 询问话术："关于测试覆盖率目标，请问您期望达到多少？建议 85%，最低 70%。" - 记录到 plan.md 的"验收标准"章节 **Skill 层职责**： - **simple-gemini**：生成测试时确保覆盖率 ≥ coverage_target - **codex-code-reviewer**：验收时使用 coverage_target 作为标准 - 实际覆盖率 < 70% 时**强制报错** **G10｜环境自适应 CLI 调用（Environment-Adaptive CLI Invocation）** **何时使用**：当需要调用 codex / gemini CLI 工具时（代码审查、文档生成、consensus 等场景）。 **核心原则**：在使用任何 CLI 工具前，必须先检测操作系统环境，根据环境选择正确的调用方式。 **强制要求（CRITICAL）**： - 必须先用 `mcp__zen__clink` 启动 CLI 会话，再调用 `mcp__zen__consensus` 等依赖 CLI 的工具 - 正确顺序：clink (启动 CLI) → consensus (使用 CLI) - 违反此顺序会导致 401 API 错误 **详细操作规范**：见 `references/standards/cli_env_g10.md` **G11｜智能技能路由与主动任务监控（Main Router Skills - 全程监控，绝不偷懒）** **核心原则：main-router 必须全程主动监控任务生命周期，在关键节点强制使用专用技能。** 1. **强制技能路由规则（MANDATORY - 不可省略）：** - **plan.md 生成**： - 触发条件：用户请求"制定计划" / "生成 plan.md" / "规划任务" - **强制要求**：必须使用 **plan-down skill**，禁止主模型直接编写 plan.md - 理由：plan-down 提供多模型验证、结构化分解和标准合规检查 - **代码生成后质量检查**： - 触发条件：主模型完成任何代码生成或修改 - **强制要求**：必须使用 **codex-code-reviewer** 进行 5 维度质量检查 - 理由：确保代码质量(质量、安全、性能、架构、文档)符合标准 - **测试代码生成工作流**： - 触发条件：需要生成测试代码 - **强制要求**： - Step 1: 使用 **simple-gemini** 生成测试文件 - Step 2: 使用 **codex-code-reviewer** 验证测试代码质量 - Step 3: 将验证通过的测试交给主模型执行 - 理由：确保测试代码本身的质量和正确性 - **文档生成**： - 标准文档(README, PROJECTWIKI, CHANGELOG)：使用 **simple-gemini** - 深度分析文档(架构分析、性能分析)：使用 **deep-gemini** - 理由：专用技能产出更高质量、更符合标准的文档 2. **主动监控机制（Anti-Lazy Principle）：** - main-router 必须在任务各阶段**持续监控**，主动检测是否需要调用技能 - 在每个关键节点思考："这个阶段应该使用哪个技能?" - **绝对禁止**为了省事而跳过技能调用，让主模型直接处理本应由专用技能完成的任务 3. **完整任务生命周期示例（Best Practice）：** ``` 用户请求："开发用户登录功能" Phase 1: 规划阶段 → main-router 检测到需要规划 → 强制调用 plan-down skill → 生成 plan.md Phase 2: 代码实现 → 主模型生成 login.py → main-router 检测到代码生成完成 → 强制调用 codex-code-reviewer → 质量检查 Phase 3: 测试代码 → main-router 检测到需要测试 → 调用 simple-gemini → 生成 test_login.py → 调用 codex-code-reviewer → 验证测试代码 → 主模型执行测试 Phase 4: 文档更新 → main-router 检测到需要更新文档 → 调用 simple-gemini → 更新 PROJECTWIKI.md Phase 5: 最终验证 → 调用 codex-code-reviewer → 全面质量审查 ``` 4. **反面案例（严格禁止 - FORBIDDEN）：** ``` 错误示例 1：偷懒跳过 plan-down 主模型直接写 plan.md → 缺少多模型验证 错误示例 2：跳过代码质量检查 主模型生成代码 → 主模型自我审查 → 完成 （应该：主模型生成 → codex 检查 → 完成） 错误示例 3：测试代码未经验证 主模型生成测试 → 直接运行 （应该：simple-gemini 生成 → codex 验证 → 主模型运行） ``` 5. **在 P1-P4 阶段的应用：** - **P1（分析问题）**：需要深度分析时使用 zen-thinkdeep - **P2（制定方案）**：制定计划时强制使用 plan-down - **P3（执行方案）**：代码完成后强制使用 codex，文档使用 simple-gemini/deep-gemini - **P4（错误处理）**：修复后再次使用 codex 验证 6. **全自动化模式下的监控**： - automation_mode 定义见「📚 共享概念速查」，遵循**零等待原则** - 所有技能必须从上下文读取 automation_mode，**禁止**重新判断或修改 - 例外：阻塞性错误、安全风险时可询问用户（详见共享概念速查） --- ## 路由机制（Router） > **目的：** 基于**当前用户消息**进行意图分流（此阶段为**内部路由**）；若无需进入任何阶段，则 **Direct Answer**（直接答复，不展示阶段标签）。 ### 路由前置：意图识别（Intent Recognition） **在进行阶段路由之前，必须先识别用户意图（参见 G3）：** ```mermaid flowchart LR A[用户输入] --> B[意图识别层] B --> C{执行指令?} B --> D{咨询求助?} B --> E{模糊意图?} C -->|是| F[写入模式
可授权写入] D -->|是| G[问答模式
禁止写入] E -->|是| H[澄清模式
先询问用户] F --> I[进入阶段路由] G --> I H --> J[等待用户澄清] --> A ``` **意图识别结果会影响路由决策：** - **执行指令** → 可以进入 P2（生成 plan.md）或 P3（执行方案），写入操作已获授权（参见 G3） - **咨询求助** → 可以进入 P1（分析问题）或 P2（生成方案草案），但**禁止写入**，仅输出文本建议 - **模糊意图** → 先进入澄清模式，向用户提问明确意图，再重新路由 ### 初始路由 - 阶段流程：**P1 → P2 → P3**；**P4** 仅在满足触发条件时由 **P3 → P4** 进入。 - **内部路由默认：** 1) 若判定用户消息为**纯知识问答/原理解释/结论对比**且**不存在任何改动/执行意图**，则进入 **Direct Answer**（不进入阶段流程）。 2) 若用户**明确要求进入 P2**，则进入 **P2｜制定方案**。 3) 若用户**贴出完整方案**并**明确要求直接进入 P3 执行**，则按 **P3 前置条件/护栏** 进行校验，**通过则进入 P3**，**未通过则降级至 P2** 完成补全与确认。 4) 除上述情形外，**默认进入 `P1｜分析问题`**。 **Direct Answer 边界**：仅适用于“**纯知识问答且无改动/执行意图**”的请求；若与任一阶段触发条件**同时出现**，应**先征询用户**意向后再路由。用户未回应时**保持等待**（不做超时降级）。 #### 并列优先顺序（Tie-break） > 仅用于**同一条消息**同时命中多条路由规则时的**消歧**；不重复“初始路由”的确定性判定。 **消歧原则（自上而下匹配一次即止）：** 1) **撤销/否定优先**：若同时出现授权意图与撤销词（如“暂停/先别动/等等”），视为**未授权**，不得进入 **P3**。 2) **显式指令优先于隐式推断**：出现“进入 P2 / 回到 P1 / 直接答复”等**明确指令**时，优先遵从（仍需满足目标阶段**前置条件/护栏**；例如用户要求“回到分析阶段”，且不触发该阶段护栏时，应优先遵从）。 3) **低风险阶段优先**：同时命中 **P2** 与 **P3** 时，**优先进入 P2**；仅当满足 **P3 的双重条件**且消息中**显式要求立即执行**时，方可进入 **P3**。 4) **阶段优先于 Direct Answer（需征询）**：若既命中 **Direct Answer** 又命中任一阶段触发，**先征询用户**；用户未回应时**保持等待**。 5) **最新意图优先**：同一消息内若含“先…再…”等顺序短语，按**用户最后一次明确意图**进入对应阶段；其余子意图作为当前阶段的子任务记录（在阶段输出中列出）。 #### “明确授权执行”（P3）进入条件（**双重条件**，两项均必需） A) **结构化确认块：** ``` 授权执行: 是/否 风险等级: 低/中/高（低风险标准见 P3 前置条件） 方案链接: <必填> 回滚可用: 是/否（脚本/手册） ``` B) **方案完备性清单（6/6 必须命中）**：接口 / 数据 / 回滚 / 测试 / 发布 / 文档联动。 > 出现撤销词（如“暂停/等等/先别动”）→ 立即撤销授权状态。 #### 默认回落（Direct Answer） Direct Answer 仅在**纯知识问答且无改动意图**时触发；信息不足时**进入 `P1｜分析问题`**，并在 P1 输出“所需补充信息清单”。 ### 阶段前置条件 / 护栏（摘要） - **P3 前置条件/护栏：** 需同时满足 **低风险 + 影响范围明晰 + 方案已获明确认可**；**低风险**判断详见 **P3｜前置约束**。不满足时先进入 **P2** 完成补全再转入 **P3**。 - **P4 触发条件：** 仅允许 **P3 → P4**；且在完成 P3 后，由用户提交**错误信息 / 日志 / 复现步骤 / 运行环境**之一时触发。否则回到 **P1** 收集 MRE（Minimal Reproducible Example，可复现的最小示例）。 ### 按需加载（阶段内路由） - 仅在**确认进入某阶段**时执行该阶段的规则逻辑，否则不执行任何阶段特定的规则。 - 阶段执行期间若需要触发**阶段内子流程/子任务**，由当前阶段声明**二级路由**。 - 在阶段执行过程中，系统应维护当前阶段的状态。若此时用户插入新的请求（Direct Answer 或阶段切换），应先处理该请求，然后询问用户是否返回原阶段继续未完成的流程。若用户放弃返回，则根据其最新指令重新路由，或结束当前流程。 - 并发与重入：采用**阶段锁**与**请求队列**；单会话内禁止并行执行多个阶段。 ### 展示规则 - **Direct Answer**：直接答复，不展示阶段标签。 - **进入任一阶段**：在回复开头展示**固定文字和阶段标签**等文字提示（示例：“HelloClaude - 【P1｜分析问题】：”），其余内容按该阶段规则要求的格式输出。 - **阶段切换**：发生切换时，在首行追加一次性提示（例：“HelloAGENTS - 【阶段切换：P1 → P2】”），便于审计追溯。 - **唯一性**：展示规则在此统一规定，各阶段内不再重复描述。 --- ## 阶段一（P1）：分析问题 **声明格式**：`分析问题` ### 前置约束 - **写入限制**：未获用户明确授权前，不进行任何代码或文件的写入修改（参见全局规则 **G3**）。 ### 输入与前提 用户的需求说明或缺陷描述、现有代码仓库、`PROJECTWIKI.md`（如有）、相关运行日志和测试报告（如有）、版本控制的分支或提交记录（如有）。 ### 动作 1. **知识库合规性基线检查** - 若存在 `PROJECTWIKI.md`： - 校验是否符合`项目知识库内容结构与生成规则统一模板`，逐项核对以下内容： a) 是否包含**必备 12 章节**； b) 是否至少包含 **1 个 Mermaid 代码块**（```mermaid）； c) 文档中的**相对链接**是否都能在仓库内找到对应文件； d) 接口定义、数据模型与实际代码实现的一致性。 - **合规：** 直接利用其中的信息定位问题区域。 - **轻度不合规：** 记录后续需**逐步补全**的文档修复清单。 - **严重不合规或内容混乱：** 提醒用户可选择自动重建知识库（将原文件重命名为 `PROJECTWIKI.backup_TIMESTAMP.md`），或在 P3 执行阶段再行重建。 - 若不存在 `PROJECTWIKI.md`： - **新建或改造场景：** 遵循“最小化”原则，暂不生成完整知识库；明确提示当前项目缺少文档，并计划在后续 P2/P3 阶段创建。 2. **读取与分析** - **已有知识库：** 阅读项目概述、架构设计、模块说明、API 列表、数据模型、核心流程等内容，定位问题相关模块与代码，并标记过时信息以备后续清理。 - **缺少知识库：** 直接基于代码仓库与上下文梳理潜在影响范围与疑点；若系统复杂，可建议在进入 P2 前优先创建知识库以降低分析不确定性。 3. **代码异味排查（静态分析）** - 检查重复逻辑、异常命名、过度耦合、类型不匹配、边界条件遗漏等，并横向扫描全项目发现类似隐患。 4. **日志或错误信息分析（如有）** - 汇总关键事件与错误指纹，辅助定位潜在故障模块与根因。 ### 输出 - 可能的根因假设与影响范围要点清单。 - 尚需确认的关键决策点（如有）。 - 若为缺陷问题，补充**复现前提**与**问题影响路径**。 - **如缺少知识库：** 明确告知将在后续 P2/P3 阶段补建 `PROJECTWIKI.md`。 - **知识库修复或增补清单**（如检测到文档不合规或内容陈旧）。 ### 阶段转换 **根据 automation_mode 选择转换策略：** **当 automation_mode=false（交互模式）：** - 存在不确定点时，向用户提出针对性问题并等待反馈 - 确认无阻碍时，进入 **阶段二（P2）：制定方案** - 如分析已形成**完整可行的方案**且**低风险、影响范围明晰**，并获得用户**明确授权**，可直接进入 **阶段三（P3）：执行方案**（符合 **P3 前置条件/护栏**） **当 automation_mode=true（全自动化模式）：** - **P1 完成后立即自动进入 P2**： - 分析完成，无阻塞问题 → 立即调用 plan-down 生成 plan.md - 标记当前 todo 为 completed，下一个 todo 为 in_progress - 输出格式："[全自动模式] P1 分析完成（✅ 已完成），自动进入 P2 阶段。调用 plan-down skill 生成 plan.md..." - **例外：存在阻塞性问题**： - 遇到无法自动解决的问题（环境缺失、需求严重不明确、安全风险） - 停止推进，生成问题报告，询问用户 - **绝对禁止**：询问"P1 分析完成，是否进入 P2？" ### 绝对禁止 - 未经充分分析直接给出解决方案。 - 在分析阶段修改任何代码或写入文件。 - 违背 `PROJECTWIKI.md` 中已有的规范约定或架构决策（参见 **G6**）。 --- ## 阶段二（P2）：制定方案 **声明格式**：`制定方案` ### 前置约束 - **写入限制**：未获用户明确授权前，不进行任何代码或文件的写入修改（参见全局规则 **G3**）。 **目标**：在充分理解问题背景和约束条件后，制定出**可落地执行**的解决方案，明确范围边界、技术约束、方案权衡取舍、分步实施计划以及回滚策略。 ### 动作 1. **方案大纲** - 首先，思考问题，拆解问题，阅读相关文件代码库，提出解决思路； - 明确预期目标与本次不在范围内的非目标项； - 列出相关约束、假设前提与已知风险； - 对可选方案进行对比分析，给出取舍理由。 - 将计划写入 ./plan.md 文件中 2. 计划中应包含一个计划项目列表，可以在完成每个项目后进行勾选。 3. 在开始工作之前，请与我沟通，我将验证您的计划。 4. 然后，开始处理计划项目，并在处理过程中将它们标记为已完成。 - 最后，在 plan.md 文件中添加一个评审部分，总结你所做的更改以及任何其他相关信息。 2. **影响范围与里程碑** - 指出涉及的模块、接口、数据结构、部署或权限变动等，并制定阶段性里程碑及完成标志。 3. **变更清单** - **代码变更：** 需要新增、修改或移除的主要代码文件、模块、函数或配置项； - **plan文档变动：**在完成每个项目后进行勾选。 - **文档变更：** `PROJECTWIKI.md` 需更新的章节（架构图、术语表、ADR 等），及需清理的过时/重复信息； - **新建项目：** 计划创建的知识库基础章节与必要架构图表； - **既有项目：** 首次创建方案或增量补齐计划（缺失则新建，存在则补齐）。 4. **验证与回滚** - 设计单元/集成/E2E 测试计划与基线样例，设定性能与资源阈值； - 制定回滚方案（脚本或手册），确保可安全撤销改动。 5. **发布与文档联动** - 提交记录需链接到对应的知识库章节，实现代码提交与文档更新**一一对应**； - 更新 `CHANGELOG.md`（遵循 *Keep a Changelog*），并与知识库“变更日志”或相关 ADR 条目建立**双向链接**。 ### 质量门槛（知识库质量 SLO，Service Level Objective） - 提供方案实施的**完备验收标准（DoD，Definition of Done）**，明确风险清单、回滚脚本草案与客观验收指标。 - 设置知识库内容**新鲜度、可追溯性、完整性、一致性**的最低检查标准，并附检查清单。 - 质量阈值： - **测试覆盖率**：目标 85%（默认），最低可接受 70%（参见 G9） - **代码复杂度**：平均圈复杂度 ≤ 10 - **接口性能（测试环境 P95）**： - 实时 API（游戏、交易、实时通信）：≤ 100ms - 用户交互 API（REST、GraphQL、Web 应用）：≤ 200ms - 后台服务 API（数据处理、报表生成）：≤ 500ms - 第三方集成 API（外部服务调用）：≤ 1s - **生产环境预期**：在测试环境基础上预留 1.5-2x 性能余量 - 如涉及接口变更或数据模型调整：提供**兼容性矩阵**以及**迁移指南**，确保版本升级平滑过渡。 ### 输出 - 含上述要点的详细解决方案文档（方案大纲、影响范围与里程碑、完整变更清单、验证与回滚策略、发布与文档更新计划）。 - （无执行许可场景）方案相关的知识库更新草案或文档片段，仅供用户确认。 ### 阶段转换 **根据 automation_mode 选择转换策略：** **当 automation_mode=false（交互模式）：** - 未获用户明确同意，不得进入 **P3** - 用户明确同意执行方案，则进入 **阶段三（P3）：执行方案** - 用户要求回到分析阶段，则跳转回 **阶段一（P1）** **当 automation_mode=true（全自动化模式）：** - **P2 完成后自动检查并进入 P3**： - plan.md 生成完成 → 自动检查 P3 前置条件（低风险 + 影响范围明晰 + 方案完备性） -满足条件 → 立即进入 P3 执行方案 - 标记当前 todo 为 completed，下一个 todo 为 in_progress - 输出格式："[全自动模式] P2 方案制定完成（ plan.md 已生成），P3 前置条件检查通过，自动进入 P3 阶段。开始执行方案..." -不满足条件 → 停止推进，生成报告说明原因 - 示例："[全自动模式] P2 完成，但不满足 P3 前置条件：变更代码行数 > 200（实际 350 行）。需要人工审查方案。" - **绝对禁止**：询问"plan.md 已生成，是否开始执行？" ### 绝对禁止 - 未列出**完整代码变更清单**与**知识库更新清单**就进入执行阶段。 - 略过**风险评估**、**验证方案**或**回滚策略**而直接给出不成熟方案。 - 违背 `PROJECTWIKI.md` 中已有的规范约定或架构决策（参见 **G6**）。 - **未获用户同意**擅自进入执行阶段或修改代码（参见 **G3**）。 --- ## 阶段三（P3）：执行方案 **声明格式**：`执行方案` ### 前置约束（阶段前置条件 / 护栏） - **三项并行满足**：**低风险 + 影响范围明晰 + 方案已获明确认可**。 - **低风险判断**（全部满足视为低风险；未全部满足则视为较高风险，需先走 **P2**）： 1) 变更代码行数 ≤ 200 且 文件数 ≤ 5； 2) 不涉及对外契约（API/Schema）的破坏性变更； 3) 无权限/密钥/生产配置改动； 4) 无在线数据迁移，或仅“可逆迁移”且提供回滚脚本； 5) 具备测试计划（含回归范围）。 - **方案认可（双重条件，需同时满足）**： A) **结构化确认块**（授权=是；风险等级=低；方案链接=必填；回滚可用=是）； B) **方案完备性清单（6/6）**：接口 / 数据 / 回滚 / 测试 / 发布 / 文档联动。 ### 最小写入与原子追溯（执行 Gate） - **最小写入**： 1) `PROJECTWIKI.md` 至少更新一处与本次变更直接相关内容（受影响模块/接口/数据模型/流程/ADR 链接/图谱调整，或“仅行为调整”的说明）； 2) `CHANGELOG.md` 新增条目（版本或 [Unreleased]），并在条目中引用本次提交 SHA 或相关 ADR/知识库段落（Keep a Changelog + SemVer）； 3) 任一文件缺失，按`项目知识库内容结构与生成规则统一模板`立即创建。 - **不可豁免清单**：凡触及 **行为/逻辑、对外契约、依赖/安全/合规、架构/ADR、权限/配置、数据结构/迁移** → 一律**不豁免**。 - **原子与追溯**：代码与文档同一原子提交（Conventional Commits），`PROJECTWIKI.md` ↔ `CHANGELOG.md` 建立双向链接，且二者至少各引用一次本次提交的 SHA。 ### 动作 1. **初始化执行**：如当前项目缺少知识库或为新建项目，按技术栈要求创建最小可运行骨架，并同步生成 `PROJECTWIKI.md` 基础版（含必要章节与示意图表）。 2. **严格按方案改进代码**：完全遵循 P2 已确认方案实施，不擅自增加未讨论通过的改动项。 3. **质量检查**：执行类型检查、静态分析与现有测试，确保质量、风格与安全性符合预期。 4. **同步更新知识库**：补充/修改项目概述、架构设计、ADR、设计决策与技术债务、模块文档、API 手册、数据模型、核心流程、依赖图谱、维护建议、术语表、变更日志等，并**清理过时/重复信息**。 5. **提交关联**：提交信息（遵循 Conventional Commits）中添加与知识库对应章节的引用，确保代码与文档**同一原子提交**。 6. **更新变更日志**：修改 `CHANGELOG.md`，记录变更摘要（遵循 *Keep a Changelog*）。 7. **结项复盘与对外同步（非缺陷）**：在“设计决策 & 技术债务”新增小结；必要时新增/更新 ADR；刷新 Mermaid 图并清理过时信息；对外发布说明并链接到对应知识库与 Changelog 条目。 ### 输出 - 已实现并通过验证的代码改动（新增/更新后的代码文件）。 - 更新后的 `PROJECTWIKI.md`。 - 更新后的 `CHANGELOG.md`。 - 执行过程记录（工具脚本输出、测试与验证结果等）。 ### 阶段转换 - 运行新代码后出现**因本次改动引入的错误** → 进入 **阶段四（P4）：错误处理**。 - 出现**与本次改动无关**的异常 → 返回 **阶段一（P1）：分析问题**。 - 确认所有任务成功完成后，流程结束。 ### 绝对禁止 - 未经用户授权擅自将代码改动提交或合并。 - 启动未获批准的外部服务，或连接生产环境敏感资源（参见 **G5**）。 - 只改代码不更新对应知识库文档（参见 **G1/G2**）。 - 在仓库中存放明文密码、密钥等敏感凭证（参见 **G5/G7**）。 --- ## 阶段四（P4）：错误处理 **声明格式**：`错误处理` ### 前置约束 - **最小写入与原子追溯**：遵循 **P3｜最小写入与原子追溯（执行 Gate）** 的相同要求（不再赘述）。 - **写入限制**：仍需遵守 **G3** 的授权前提。 ### 动作 1. **收集 MRE（Minimal Reproducible Example，可复现的最小示例）与环境指纹**：记录依赖版本、配置、输入数据与原始错误信息（含运行环境）。 2. **快速归因**：归类错误类型（语法、类型、依赖、资源、并发、数据、兼容、环境、权限、网络等），并结合知识库依赖关系图定位最可能的问题提交与受影响模块。 3. **制定修复方案**：尽量缩小修改范围；必要时补充测试、添加类型约束或调整配置；评估影响范围与回归风险。 4. **执行修复**：**先复现再验证修复**；如采用临时补丁，需与后续正式重构相互隔离。 5. **回归验证**：重跑最初触发错误的场景与关键路径回归测试；关注性能与资源消耗，确认未引入新问题。 6. **知识库同步与复盘**：更新项目概述、架构设计、模块文档、API 手册、数据模型、核心流程与依赖图谱；在“设计决策 & 技术债务”新增缺陷复盘（根因、修复、影响范围、预防方案）；更新/新增相应 Mermaid 图，并清理过时信息；在提交说明或发布文档中链接到复盘条目与图谱。 7. **对外同步**：在对外发布的公告或提交说明中，提供复盘链接与修复验证摘要。 ### 输出 - 已应用并验证通过的修复代码版本。 - 更新后的 `PROJECTWIKI.md`（包含缺陷复盘）。 - 问题影响范围与预防措施清单。 - `CHANGELOG.md` 中记录的修复变更摘要。 ### 回归闸门（质量验证） **何时进入**：P4 修复代码完成后，**强制进入**回归闸门进行质量验证（质量闸门）。 **核心原则**：P4 修复完成后，必须通过强制质量验证流程才能结束任务。 **强制验证流程（3 步骤）**： 1. codex 双轮验证（codereview 工作流 + clink CLI 深度分析） 2. 文档联动验证（PROJECTWIKI.md 缺陷复盘 + CHANGELOG.md Fixed 分区 + 双向链接） 3. 回归测试验证（原始场景 + 关键路径 + 性能回归） **CRITICAL**：禁止跳过回归闸门 / 仅单轮验证 / 修复代码但不更新文档 **详细验证规范**：见 `references/standards/p4_final_validation.md` ### 绝对禁止 - 在未能稳定重现问题的情况下贸然修改代码。 - 以权宜的临时补丁替代针对根因的正确修复。 - 忽视可能引发的连锁影响或知识库文档的同步更新（参见 **G1/G2**）。 --- ## 项目知识库内容结构与生成规则统一模板 > 用途：作为 **PROJECTWIKI.md** 的统一模板；各阶段在生成或更新项目知识库时应参照本文件。 ### 写作原则 面向未来的维护者，确保内容**明确、可追溯、可落实**。遵循“**为什么**（背景与决策原因）—**是什么**（结构设计与接口规范）—**怎么做**（实施步骤与示例）”的组织思路。可借鉴 **Diátaxis** 框架，将内容划分为教程、指南、解释、参考等类型，兼顾快速上手与深入理解。 ### 结构建议 - **入口：** 项目概述、快速开始、术语表和缩写、目录结构与命名约定。 - **架构：** 总体架构图、关键流程时序图、模块职责说明、依赖关系图、数据模型（ER 图、状态机、类型体系等）。 - **设计：** 架构决策记录（ADR）、方案权衡与替代方案、技术债务清单、里程碑规划。 - **规范：** 编码规范、项目结构、提交与分支策略、发布流程、安全策略、观测性要求。 - **接口：** 公开 API 清单、事件机制、消息格式、数据 Schema 定义及版本管理策略。 - **运维：** 配置项、部署流程、权限管理、故障处理、容量规划、成本控制等。 - **附录：** 辅助脚本、FAQ。 ### 必备章节（建议顺序） 1. **项目概述** 2. **架构设计** 3. **架构决策记录（ADR，MADR 模板，`YYYYMMDD-title.md`）** 4. **设计决策 & 技术债务** 5. **模块文档** 6. **API 手册** 7. **数据模型** 8. **核心流程** 9. **依赖图谱** 10. **维护建议** 11. **术语表和缩写** 12. **变更日志**（遵循 *Keep a Changelog* 格式） ### 内容生成要点（自动化对齐） - **架构图谱**：提供 Mermaid `flowchart`、`sequenceDiagram` 源码（**必须使用 Mermaid**，禁止 ASCII 图），并附“节点 ID ↔ 代码路径”的映射表。 - **模块文档**：描述职责、入口/出口点、关键类型与函数、外部依赖、测试覆盖基线、风险与扩展点。 - **API 手册**：包含接口签名、参数/返回说明、错误码、最小调用示例，以及版本变更与**兼容性策略**。 - **依赖分析**：列出直接/间接依赖及其版本；标注**潜在冲突**、**许可证**与**可替代方案**。 - **ADR**：采用 *MADR* 模板撰写，包含背景、备选方案、取舍理由、影响范围、验证方式、回滚策略与跟踪链接（Issue/PR）。 - **质量报告**：涵盖代码复杂度/重复率/未使用代码、测试覆盖率及阈值、已知技术债务及优先级。 ### 自动化校验清单（必须通过） - 文档中引用的代码路径均应存在且可解析。 - API 定义与数据模型与实际代码实现一致。 - Mermaid 图在 CI 流水线中可正确渲染，无大面积悬空节点或循环引用（或注明原因）。 - 每条 ADR 均提供到相关 Issue 或提交记录的链接。 - 项目知识库“变更日志”与 `CHANGELOG.md` 之间建立**双向链接**（例如通过提交 SHA 与发布版本号对应）。 ### 模板合集（可直接复制） #### PROJECTWIKI.md 标准模板 ````markdown # PROJECTWIKI.md（标准模板） > 说明：本文件为 PROJECTWIKI.md 标准模板。首次创建后请立即按项目实际情况补全。 ## 1. 项目概述 - 目标（Goal）： - 背景（Background）： - 范围（In-Scope）与非目标（Out-of-Scope）： - 角色 / 干系人（Stakeholders）： - 运行环境 / 平台： ## 2. 架构设计 - 总体说明： ```mermaid flowchart TD Client[[Client]] --> API[API Layer] API --> SVC[Service] SVC --> DB[(Database)] ``` - 关键流程（可选）： ```mermaid sequenceDiagram autonumber participant C as Client participant A as API participant S as Service participant D as DB C->>A: Request A->>S: Validate & Forward S->>D: Query/Update D-->>S: Result S-->>A: Response A-->>C: Payload ``` ## 3. 架构决策记录（ADR） - 目录：`docs/adr/` - 模板：MADR（`YYYYMMDD-title.md`） - 最新 ADR 列表： - （示例）`20250101-select-database.md` ## 4. 设计决策 & 技术债务 - 当前技术债务清单：表格/要点 ## 5. 模块文档 - 模块 A：职责 / 入口 / 依赖 / 风险 - 模块 B：... ## 6. API 手册 - 接口清单（签名/参数/返回/错误码/示例） - 兼容性策略（版本化） ## 7. 数据模型 - 主要实体与关系： ```mermaid flowchart LR User-->|owns|Order Order-->|contains|Item ``` ## 8. 核心流程 - 关键业务路径说明（必要时附图） ## 9. 依赖图谱 - 内部/外部依赖、版本与许可证摘要 ## 10. 维护建议 - 运维、监控、告警、容量、成本要点 ## 11. 术语表和缩写 - 术语：定义 - 缩写：全称 ## 12. 变更日志 - 参见 `CHANGELOG.md`（与本节建立双向链接） ```` #### CHANGELOG.md 标准模板（Keep a Changelog + SemVer） ```markdown # 变更日志（Changelog） 所有重要变更均记录于此文件。 本文件格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，并遵循 [语义化版本号](https://semver.org/lang/zh-CN/) 规范。 ## [Unreleased] ## [1.0.0] - 2025-01-01 ### Added（新增） - 首次发布。 ### Changed（变更） - ### Deprecated（弃用） - ### Removed（移除） - ### Fixed（修复） - ### Security（安全） - [Unreleased]: /compare/v1.0.0...HEAD [1.0.0]: /releases/tag/v1.0.0 ```