AI 研发 Skill 体系现状与演进路线

进入图形化现场讲解版

进入实际项目操作详解：初始化、PRD-A、经验沉淀与 PRD-B 对照验证

1. 为什么做

日常研发主要消耗在两类工作：

• PRD 开发：读需求、补问题、查旧代码、拆工时、写设计、实施、验证和发布。
• 问题排查：查日志、SQL、MQ 和调用链，经过多轮假设与验证后才能找到根因。

真正浪费时间的不是第一次分析，而是结论只留在聊天里：

• 换窗口后重新解释需求。
• 换 Agent 后重新查项目入口和历史链路。
• 多项目同时修改时，不知道其他仓库正在改什么。
• 同类问题再次出现时，重复搜索和试错。

目标是把聊天中的有效结论变成项目内可恢复、可校验、可复用的研发状态。

2. 总体架构

flowchart TB
    A["公司控制面<br/>总纲 · 项目注册 · 公共 Skill · 跨项目索引"]
    B["统一发现入口<br/>Codex / Claude Code / 其他 Agent"]
    C["项目入口<br/>AGENTS.md · project.yaml · 项目总入口 Skill"]
    D["活动任务恢复<br/>active-tasks → resume → handoff"]
    E["变更包<br/>proposal · requirement · design · tasks · tests"]
    F["持续检查点<br/>immutable events → planning-state → Revision"]
    G["实现与门禁<br/>R → D → T → TC → delivery"]
    H["归档与经验回流<br/>project · skills · candidates · archive"]

    A --> B --> C --> D --> E --> F --> G --> H
    H -. "项目经验" .-> C
    H -. "跨项目能力" .-> A

各层职责清晰分开：

• 公司层负责通用方法、项目发现和跨项目协调。
• 项目层负责仓库事实、限制、业务 Skill 和历史交付。
• 任务包按场景保存一次需求、Bug 或持续故障调查的状态与证据；低风险快速变更默认不建包。
• 聊天窗口只负责操作，不作为唯一事实源。

3. 外层与项目目录

ai-engineering-playbook/
├── company/                       # 公司研发总纲与治理规则
├── project-registry/              # 项目 ID、仓库、入口 Skill、成熟度
├── shared-skills/                 # 项目路由、PRD、代码、日志、SQL、API、测试、发布、沉淀
├── cross-project-skills/          # 跨仓业务能力
├── cross-project/
│   ├── active/<EPIC-ID>/          # 父级 Epic 与项目路线图
│   └── active-tasks.yaml          # 跨项目活动任务索引
└── scripts/                       # 初始化、扫描、索引和治理校验

project/
├── AGENTS.md                      # Agent 自动读取的项目入口规则
├── .agents/skills/                # 项目 Skill 发现路径
└── doc/ai/
    ├── index.md                   # 项目 AI 资料导航
    ├── active-tasks.yaml          # 当前需求、冲突、依赖
    ├── project/                   # 架构、代码、数据、环境、日志、发布
    ├── skills/                    # 项目 Skill 唯一可编辑源码
    ├── changes/
    │   ├── active/<REQ-ID>/       # 进行中变更包
    │   └── archive/<YEAR>/        # 已验证历史包
    ├── candidates/                # 尚待第二次验证的经验
    ├── templates/                 # PRD / Bug / Incident 场景模板
    ├── scripts/                   # create/resume/checkpoint/validate/archive
    └── tests/                     # 机制测试与无历史对照测试

4. 一个旧项目如何初始化

项目初始化的输入不是当前已训练好的项目目录，而是一个固定历史提交的干净代码仓库。初始化器只生成 L1 研发骨架，不会凭空写入业务规则。

flowchart LR
    A["固定历史提交<br>旧代码、无 AI 资料"] --> B["只读扫描<br>语言、框架、代码与测试目录"]
    B --> C["运行初始化器<br>统一入口、项目 Skill、模板和脚本"]
    C --> D["重建任务索引<br>执行 8 项总校验"]
    D --> E["提交初始化基线<br>得到 BASELINE_SHA"]
    E --> F["新聊天输入第一个 PRD<br>创建 Revision 1 与需求包"]

逐步动作与产物：

初始化前：

legacy-project/
├── application/ 或 app/
├── config/
├── tests/
└── 没有 AGENTS.md / doc/ai / 项目 Skill

初始化后：

project/
├── AGENTS.md
├── CLAUDE.md / GEMINI.md / Copilot / Cursor 薄入口
├── .agents/skills/<project>-project-maintainer
└── doc/ai/
    ├── project/ + standards/ + runbooks/
    ├── templates/ + scripts/ + tests/
    ├── changes/ + active-tasks.*
    └── skills/ + candidates/ + contracts/

本次使用两个完全独立的历史项目副本验证：

初始化完成只表示项目已经具备统一入口、可恢复规划和经验容器，成熟度为 L1。领域规则、日志入口、数据库关系和排障经验必须在后续真实 PRD、代码取证和验证中沉淀。

4.1 先分流场景，再调用通用能力

项目入口不是把任何任务都塞进完整 PRD 流程。总入口先识别项目，再判断任务类型和风险；项目内进入对应工作流，并按证据缺口选择数据库、日志、API、测试等能力。

flowchart TB
    U["用户自然语言输入"] --> R["总入口：识别项目 + 场景 + 风险"]
    R --> A["需求开发<br/>REQ-* 完整需求包"]
    R --> B["Bug 修复<br/>BUG-* 轻量任务包"]
    R --> C["线上问题排查<br/>只读取证；持续跟进才建 INC-*"]
    R --> D["低风险快速变更<br/>默认无包；风险升高立即转轨"]

    K["通用 Skill 能力库<br/>项目路由｜需求读取｜代码取证｜数据库｜日志｜API/Apipost｜测试审查｜发布回滚｜经验沉淀"]
    K -. "按条件调用" .-> A
    K -. "按条件调用" .-> B
    K -. "按条件调用" .-> C
    K -. "按条件调用" .-> D

多项目协同不是另一套业务流程，而是叠加在需求或 Bug 上的协调层：注册表定位仓库，父级 Epic 维护依赖，各项目仍执行自己的场景工作流。

5. 一次 PRD 的完整流转

sequenceDiagram
    participant U as 用户
    participant A as Agent
    participant I as 项目活动索引
    participant P as 需求变更包
    participant V as 验证门禁
    participant K as 项目知识

    U->>A: 提供 PRD 或需求描述
    A->>I: 查找相同/重叠任务
    I-->>A: 返回需求 ID、Revision、依赖与 handoff
    alt 已有任务
        A->>P: resume 最新状态
    else 新任务
        A->>P: create proposal / requirement / delta
    end
    U->>A: 多轮确认与纠偏
    A->>P: checkpoint，追加事件并生成新 Revision
    A->>P: current-flow → impact → design → tasks
    A->>V: 校验 R → D → T → TC
    A->>V: 实施、测试、发布与 delivery 门禁
    alt 门禁通过
        V->>K: 更新项目事实、Skill 或经验候选
        V->>P: 追加 archived 事件并归档
    else 门禁失败
        V-->>A: 保留阻断项和下一步，继续活动状态
    end

6. 多轮纠偏时，文件如何变化

检查点只在有意义的变化后产生，不保存聊天全文：

• 需求被确认或纠正。
• 重要设计决策被接受或替代。
• 阶段、阻断项或下一步发生变化。
• 实施或测试得到可复用结果。

7. 新窗口恢复算法

flowchart LR
    A["进入仓库"] --> B["读取 AGENTS.md"]
    B --> C["读取 active-tasks.md"]
    C --> D{"找到对应或重叠任务？"}
    D -- "是" --> E["resume_prd.py REQ-ID"]
    E --> F["最新 EVT 修复 state"]
    F --> G["读取 handoff 与当前阶段文档"]
    G --> H["按最新 Revision 继续"]
    D -- "否" --> I["创建新的变更包"]

常用命令：

python3 doc/ai/scripts/resume_prd.py --list
python3 doc/ai/scripts/resume_prd.py REQ-ID
python3 doc/ai/scripts/checkpoint_prd.py REQ-ID \
  --expected-revision 2 \
  --summary "产品已确认字段口径" \
  --changed-artifact requirement.md
python3 doc/ai/scripts/validate_planning.py REQ-ID
python3 doc/ai/scripts/validate_delivery.py doc/ai/changes/active/<CHANGE>/delivery.yaml
python3 doc/ai/scripts/archive_change.py REQ-ID

8. 多项目如何自动发现

flowchart TB
    E["父级 EPIC-AI-PRD-CONTINUITY<br/>roadmap.yaml"]
    R["项目注册表"]
    D["DGJ2 子任务<br/>独立 Revision / handoff"]
    S["SAAS 子任务<br/>独立 Revision / handoff"]
    P["Playbook / 初始化器<br/>统一协议"]
    X["跨项目 active-tasks<br/>按 parent_epic 自动聚合"]
    G["集成门<br/>契约 · 顺序 · 回滚"]

    E --> R
    R --> D
    R --> S
    R --> P
    D --> X
    S --> X
    P --> X
    X --> G

项目不是由模型猜出来的，而是由三类事实共同决定：

1. 项目注册表声明仓库路径、项目 ID、入口 Skill 和能力。
2. 父级 Epic 声明涉及哪些项目及依赖。
3. 每个项目变更包通过 parent_epic 回指总任务。

每个项目独立维护 Revision，避免跨仓状态互相覆盖；跨项目索引只负责聚合与提示，最终集成门负责契约、联调、发布顺序和回滚。

9. 经验如何沉淀并在下次生效

flowchart LR
    A["一次任务证据"] --> B{"是否已验证且可复用？"}
    B -- "仅本次有效" --> C["留在归档变更包"]
    B -- "首次可复用" --> D["experience-candidates.yaml"]
    B -- "稳定项目事实" --> E["project/ 或已有项目 Skill"]
    B -- "跨项目成立" --> F["shared-skills / cross-project-skills"]
    D --> G["第二次真实任务复验"]
    G --> E
    E --> H["AGENTS + 项目入口自动路由"]
    F --> H
    H --> I["下一次任务先读结论再行动"]

不会进入长期知识的内容：

• 一次性订单号、临时测试数据。
• 凭证、Cookie、Token、密码或客户隐私。
• 尚未验证的推断。
• 只对单次需求成立、没有复用价值的细节。

10. GitHub 成熟方案对照

吸收的是机制，不直接引入额外重型框架。当前项目仍使用 Markdown、YAML、Python 脚本和 Git，任何 Agent 都能读取。

11. 当前实施状态

已完成：

• DGJ2 与 SAAS 已有项目入口、活动任务索引、可恢复规划和交付门禁。
• Claude、Gemini、Copilot、Cursor 已有薄入口，全部指向同一 AGENTS.md + doc/ai + CLI 核心。
• 需求、Bug、Incident 已有独立核心模板；低风险快速变更默认无任务包。
• 项目路由器已经输出场景、风险、对应工作流、任务包策略、编码门禁和条件能力建议。
• delivery.yaml 使用条件门禁：受影响项必须 passed + evidence，不受影响项必须 not_required + reason。
• PRD/Bug 变更包支持不可变事件、Revision、handoff 和并发写保护。
• R → D → T → TC 断链会阻止完成。
• 父级 Epic 与跨项目活动索引已经能关联 DGJ2、SAAS 和 Playbook。
• 初始化器可为新项目生成同一套目录、脚本和测试。
• 归档命令只接受交付通过且 done/completed 的变更包。

下一步：

• 用团队真实工具验证薄适配器，并增加生成文件漂移检查。
• 把验证接入 GitLab/Jenkins，阻止活动索引漂移和未通过交付包合并。
• 用“无历史聊天的新 Agent”持续执行 Forward Test，记录重复提问、人工纠正和恢复成功率。
• 建立公共 Playbook 的远端版本和团队升级策略。

12. 远期目标：从局部提效到个人研发 Agent

远期目标不是继续堆叠零散 Skill，而是形成从需求到线上反馈再到经验回流的研发闭环：

flowchart LR
    A["图形化需求<br>流程、状态、影响项目"] --> B["项目架构开发<br>路由、旧链路、设计与实现"]
    B --> C["上线前 Code Review<br>PRD、Diff、兼容、测试、回滚"]
    C --> D["发布与观察<br>版本、配置、指标、时间窗"]
    D --> E["Kibana 自动发现<br>日志索引、业务键、上下游关联"]
    E --> F["本地 / 快小六排查<br>复现、远端取证、补偿"]
    F --> G["经验回流<br>项目地图、Runbook、Skill、候选区"]
    G --> B

分三阶段推进：

Kibana 自动发现不只是代替人工搜索一个关键词。它应从现象、接口、订单号、request_id 和时间窗出发，识别项目与环境，扩展稳定业务键，按时间线关联入口、异常、MQ 和回调，最后回到当前代码验证根因。

上线前 Code Review 是强制质量门。输入为 PRD 任务包、Git Diff、项目规范和发布清单，至少检查：

• R → D → T → TC 是否完整追踪；
• 公共文件、旧链路和兼容条件是否被保护；
• API、SQL、配置、MQ、权限和文档是否交付完整；
• 正常、失败、回归、发布观察和回滚是否可执行。

北极星目标：

先提升一部分效率，解放更多时间；再打造一个理解负责项目、业务规则、当前任务、个人工作习惯和风险偏好，并始终用当前代码和证据校正历史经验的 AI Agent。

13. 分享时讲七页

1. 为什么做与总体架构：重复分析、聊天丢失、多项目协同，以及公司入口到经验回流。
2. 项目初始化：历史代码 → 扫描 → L1 骨架 → 校验 → 基线 → 第一个 PRD。
3. DGJ2 项目链路：项目入口、事实、Skill 路由、变更包、门禁和沉淀。
4. 四种场景：需求、Bug、线上排查、低风险快速变更如何分流；数据库、日志、Apipost 等如何按条件调用。
5. 实战：第一次多轮纠偏，第二个窗口只靠需求 ID 恢复。
6. 多项目协同：父级 Epic、独立 Revision、并行边界和统一集成门。
7. 远期目标：图形化需求、上线前 Code Review、Kibana 自动发现、快小六远端排查和个人研发 Agent。