docs/api/<需求标识>* 等），只读命中文件。docs/ 并逐份读所有文档——概览 = 读小文件索引，不是「读所有详情」。（5 后）共识基线发布，规则编号完整，才可拆解子需求。
（8 后）FE+QA 两轮复核通过 + CONS-02 双文件一致，才可判级进实现。
（★ 前）① 判级留痕 ② 复杂必产方案且 frozen ③ 工程基线三问 ④ 核验回查判级匹配。
（10）三层：① 设计核验 ② 契约核验 ③ PRD/业务核验；判级缺失/错判 → 不通过。
docs/design/<id>-<module>-design.md 且评审通过（方案冻结 draft→frozen，评审记录留痕）；无方案文档或未冻结 = 不得进入实现管道。| 级别 | 触发条件 | 要求 |
|---|---|---|
| 复杂 | 跨模块、新架构/greenfield、契约变更、状态机、外部系统集成 | 必出技术方案文档 + 评审（frozen 才进实现）；需求探索必产 PRD+原型（UI 类）；完整实现纪律 |
| 常规 | 单模块、CRUD、纯 UI、已有模式简单延伸 | 跳过方案；轻量实现纪律（lint 单次 + 工程基线三问复核） |
| 安全敏感 | 密钥/权限/支付/资金/数据（叠加在任一级之上） | 强制安全扫描（Semgrep 或等价工具），不得降级 |
工具降级记录在案，交付核验可见；留痕 docs/records/<id>-record.md（实现记录 + 核验记录两节）。
| 目录 | 内容 | 命名 |
|---|---|---|
docs/spec/ | 共识、规则索引、团队配置、变更摘要（L1 索引 + L2 模块详情 变更摘要-<模块>.md）、影响清单 | {模块}-共识文档.md、规则索引.md… |
docs/api/ | 契约双文件（叙事 + OpenAPI） | {platform}-{item_id}-{prd_slug}-api-contract.md + -openapi.yaml |
docs/design/ | 技术方案（draft→frozen） | <id>-<module>-{prd_slug}-design.md |
docs/prd/ | 需求文档 | <date>-<slug>-prd.md |
docs/prototype/ | 交互原型 | <date>-<slug>-prototype（与 PRD 同 slug，保证回溯链） |
docs/records/ | 实现/核验记录（两节） | <id>-{prd_slug}-record.md（与技术方案同 id，优先后端子任务 key） |
docs/lessons/ | 经验沉淀（三硬标准，90 天无引用归档） | <date>-<slug>-{prd_slug}-lesson.md |
docs/ui/ | 项目级 UI 规范（复杂 UI 原型后提取，前端实现必读） | UI规范.md（模板见 templates/UI规范模板.md） |
共识-{模块}-{需求标识}.md（如 共识-桌面壳-m1.md）CON-R-{需求标识}-{序号}（各需求独立编号域，不撞号）feature/<需求标识>（如 feature/m1、feature/login）2026-08-14-m1-prd.md → m1）；常规需求手给短 slug（login）；检测 docs/ 已用 slug 避免重复| 工具 | 场景 | 要点 |
|---|---|---|
| git-commit | 提交 / 写 commit message | Conventional Commits：<type>(<scope>): <summary>；type 必选（feat/fix/refactor/perf/docs/test/chore/build/ci/style/revert）；scope 可带需求标识（m1）；summary 祈使句 ≤50 字符；body 只写非显然 why；commit 在 feature/<需求标识> 上做 |
| git-worktree | 多需求并行开发 | 一需求一 worktree = feature/<需求标识> 分支，独立工作区互不干扰；git worktree add ../<repo>-<需求标识> feature/<需求标识>；需求不做留分支/worktree，合并后清理（git branch -d + git worktree prune） |
| git-rollback | 回滚 / 撤已合并需求 | 固定三步：先列历史看清再动 → 双重确认 → 自动备份（backup/<分支>-<时间戳>）；合并过主分支 = revert 不 reset（保留历史）；reset --hard 仅限本地未推送 |
| git-pr | 提 PR / 合并需求到主分支 | 按合并模式 full/semi/manual 走流程（见下节）；push/提 PR 前最小检查：只跑受影响测试、修复再 push、禁 raw force 用 --force-with-lease、有 CI 则 PR 后查 CI（无 CI 跳过）；合并前做需求标识唯一性 gate，合并后清理 feature/<需求标识> 分支 |
项目 | 需求标识 | 模式，命中当前需求标识 → 用该模式项目 | 默认模式，需求级无覆盖 → 用项目默认docs/spec/团队配置.md 一行，不改 skill 代码m1 → m1b）+ 同步改所有引用（文档名/规则编号/契约/设计/记录）→ 再合并| 模式 | 流程 | merge 按钮谁按 | 检测合并 |
|---|---|---|---|
| full 全自主 | AI 提 PR → 合并 gate → AI 自己 merge → 清理分支 | AI | 不需要（AI 自己合，结果自知） |
| semi 半自主 | AI 提 PR → 等人工 approve → merge → 检测合并 → 清理分支 | AI 或人工（按团队约定） | 要（gh pr view <编号> --json state,mergedAt，state=MERGED = 已合并） |
| manual 人工 | AI 提 PR → 人工全权 merge → 后续推进时 检测合并 → 清理分支 | 人工 | 要（同上；gh 不可用时兜底 git branch --merged origin/main） |
三模式区别只在「merge 按钮谁按」；「检测合并」是 semi/manual 通用能力（merge 非 AI 自做时 AI 无法自知结果，必须显式检测），full 不需要。检测合并也用于继续对话时判断上一步 PR 是否已合并——未合并则提示用户，不静默继续。合并是变更 → 需要时走 change-propagation 更新变更摘要。
docs/spec/团队配置.md 对应段一行，改后生效，无需重跑 workflow-setup；未配某段 → 默认值兜底（评审 self-check、合并 full）。templates/UI规范模板.md，复制到项目 docs/ui/UI规范.md 按项目填写。验证基线 evals/：低频跑（大改动 / 发布时全量），覆盖 git 三件套触发 + 需求标识产出断言；日常小改静态检查即可。