PRACTICAL RUNBOOK · 2026-07-29

实际项目操作详解

从两个旧项目初始化开始，完整验证 PRD 多轮纠偏、换任务恢复、经验自动发现和对话轮次下降。

从第一步开始直接看对照实验先看体系架构

三个隔离 Git 仓库 总入口 + DGJ2 + SAAS

八步完整验证 初始化到第二项目复验

唯一实验变量 PRD-B 分支是否包含 PRD-A 经验

END-TO-END FLOW

现场只讲这一条主链路

前六步把一次 PRD 的多轮确认变成项目知识，后两步用相同 PRD-B 对照是否真正减少重复对话。

01 初始化 旧代码接入项目 AI 体系 02 入口验证 总入口正确路由项目 03 PRD-A 第一次生成可恢复计划 04 多轮纠偏 Revision 与事件持续增长 05 换任务恢复 不依赖原聊天继续 06 经验沉淀 规则进入项目知识层 07 PRD-B 对照 相同输入比较有无经验 08 评分复验 DGJ2 结论再由 SAAS 复验

一次性准备 01

STEP 01

初始化两个项目并注册总入口

把只有旧业务代码的 DGJ2、SAAS 变成 Agent 可自动进入、可恢复任务、可执行交付门禁的项目。

本步使用的 Skill / 协议 project-skill-initializer

在总入口新任务中发送

请使用 project-skill-initializer 初始化并注册下面两个项目。

总入口：
/Users/zhoujiangbin/code/ai-skill-validation-20260728/ai-engineering-playbook-demo

项目：
1. /Users/zhoujiangbin/code/ai-skill-validation-20260728/dgj2.0
2. /Users/zhoujiangbin/code/ai-skill-validation-20260728/saas

要求：
1. 先校验 Git 状态和历史起点。
2. 两个项目全部通过初始化校验后，再更新总入口注册表。
3. 重建跨项目索引并验证 project-task-router。
4. 输出 onboarding-report.md 和 onboarding-report.json。
5. 不创建提交、不推送、不修改业务代码。

完整现场演示的起点与命令

ROOT=/Users/zhoujiangbin/code/ai-skill-validation-20260728
PLAYBOOK="$ROOT/ai-engineering-playbook-demo"

git -C "$PLAYBOOK" checkout codex/demo-onboarding-start
git -C "$ROOT/dgj2.0" checkout -B codex/demo-dgj2-initialization \
  0e2e4fa3d898c302710db95d899f185117fe7a1e
git -C "$ROOT/saas" checkout -B codex/demo-saas-initialization \
  43e16714139c91dbb1de04360fae7bb8c14e4dd6

python3 "$PLAYBOOK/shared-skills/project-skill-initializer/scripts/onboard_projects.py" \
  --playbook "$PLAYBOOK" --allowed-root "$ROOT" \
  --expected-head dgj2=0e2e4fa3d898c302710db95d899f185117fe7a1e \
  --expected-head saas=43e16714139c91dbb1de04360fae7bb8c14e4dd6 \
  --project dgj2 dgj2-validation "DGJ2.0 Skill 验证项目" "$ROOT/dgj2.0" \
  --project saas saas-validation "SAAS Skill 验证项目" "$ROOT/saas" \
  --alias dgj2=dgj --alias dgj2=大管家

本步会新增或更新的产物

项目根入口：AGENTS.md、CLAUDE.md、GEMINI.md
Agent 发现：.agents/skills/<project>-project-maintainer
项目知识：doc/ai/project、skills、contracts、runbooks
任务机制：doc/ai/changes、templates、scripts、active-tasks.*
总入口注册：project-registry/projects.yaml
跨项目索引：cross-project/active-tasks.*
执行报告：project-registry/onboarding-report.{md,json}

怎样算本步通过

两个项目初始化校验全部 PASS；注册表能路由到验证副本；业务代码没有变化。

现场注意： 初始化只建立 L1 容器和门禁，不会凭空生成业务经验。真正经验来自后续 PRD 和 Bug 的已验证结论。

每次演示前 02

STEP 02

验证总入口能找到正确项目

证明以后只在总入口创建任务，也能根据项目名或 PRD 证据加载正确项目，而不会读取正式仓库。

本步使用的 Skill / 协议 project-task-router

先发送只读路由冒烟

请使用总入口的项目路由协议处理下面的任务，暂时不要写文件：
“DGJ2 折扣活动需求需要确认是否同时涉及 SAAS。”

请列出：
1. 识别到的项目；
2. project-registry 中的路径证据；
3. 每个项目需要加载的入口文件；
4. 是否需要读取跨项目索引。

禁止访问正式 DGJ2 和正式 SAAS 仓库。

固定基线复核

/Users/zhoujiangbin/code/ai-skill-validation-20260728/demo/scripts/verify_total_entry.sh

本步会新增或更新的产物

聊天输出：识别 dgj2、saas 两个验证项目
读取入口：AGENTS.md、doc/ai/index.md、project.yaml
读取任务：active-tasks.md / active-tasks.yaml
读取 Skill：对应 project-maintainer/SKILL.md
多项目时读取 cross-project/active-tasks.*

怎样算本步通过

输出路径全部位于 ai-skill-validation-20260728；校验脚本最后显示 PASS。

现场注意： verify_total_entry.sh 用于固定基线复核，不是初始化器的前置依赖。完整初始化演示结束并切回固定基线后再运行。

第一次学习 03

STEP 03

发送 PRD-A，生成第一版可恢复计划

让 Agent 从真实代码和旧链路形成需求、影响、设计和任务计划，并把聊天状态写进项目。

本步使用的 Skill / 协议 prd-to-implementation-delivery + dgj2-validation-project-maintainer

新任务发送统一提示，再粘贴 PRD-A 正文

这是一次总入口发起的 PRD 设计计划验证。

要求：
1. 先从总入口识别目标项目，再加载项目 AGENTS.md、doc/ai 和入口 Skill。
2. 只允许访问注册表中的验证项目。
3. 为需求创建可恢复的 PRD change package。
4. 先读取真实代码和旧链路，再形成需求、影响、设计和任务计划。
5. 当前不修改业务代码、不部署。
6. 未明确的问题集中提出，不静默假设。
7. 每次确认关键规则后执行 checkpoint。

需求编号：REQ-EVAL-DGJ-A
目标项目：DGJ2

以下是 PRD：
【粘贴 demo/inputs/dgj2/01_prd_a.md 的完整正文】

建立学习分支并检查首轮产物

git -C /Users/zhoujiangbin/code/ai-skill-validation-20260728/dgj2.0 \
  checkout -B codex/eval-dgj2-prd-a 272bea0636

cd /Users/zhoujiangbin/code/ai-skill-validation-20260728/dgj2.0
python3 doc/ai/scripts/resume_prd.py REQ-EVAL-DGJ-A
find doc/ai/changes/active -maxdepth 2 -type f | sort
git status --short

本步会新增或更新的产物

proposal.md：目标、范围和非目标
requirement.md / spec-delta.md：R-ID 与增量规则
current-flow.md / impact-analysis.md：代码证据和影响面
design.md / tasks.md：D-ID、T-ID 与实施顺序
planning-state.yaml：phase、status、Revision
events/EVT-*.yaml：不可变决策与纠偏事件
handoff.md：换任务时的当前状态
active-tasks.*：项目级活动任务索引

怎样算本步通过

能恢复 REQ-EVAL-DGJ-A；首轮问题明确区分“旧代码事实”和“产品待确认”，没有修改业务代码。

现场注意： PRD 正文必须粘贴到聊天。不要让实验 Agent 读取项目外的金标准和纠偏答案，否则对照结果无效。

多轮纠偏 04

STEP 04

一次发送一轮产品确认，观察状态持续增长

验证多轮对话不只是更新聊天，而是把每个已接受结论写成可审计 Revision、事件和计划变更。

本步使用的 Skill / 协议 prd-to-implementation-delivery

每轮产品确认后追加同一条执行要求

这是产品已经确认的规则：
【只粘贴 demo/inputs/dgj2/02_prd_a_corrections.md 中当前一轮】

请同步更新：
1. requirement 和 spec-delta；
2. current-flow 和 impact-analysis；
3. design 和 tasks；
4. planning-state、events、handoff 和 active index。

使用当前 Revision 执行 checkpoint；然后告诉我新的 Revision、剩余问题和下一步。

每轮之后都检查

cd /Users/zhoujiangbin/code/ai-skill-validation-20260728/dgj2.0
python3 doc/ai/scripts/resume_prd.py REQ-EVAL-DGJ-A
git diff -- doc/ai/changes/active doc/ai/active-tasks.md doc/ai/active-tasks.yaml

本步会新增或更新的产物

planning-state.yaml：Revision +1
events/：新增一条不可变事件
handoff.md：更新为最新确认结果
requirement/spec/design/tasks：同步纠偏
active-tasks.*：最新 phase、status、summary

怎样算本步通过

四轮确认形成 FS-LIMIT-001～005；旧结论不被后续轮次覆盖或遗忘。

现场注意： 演示时一次只发一轮。一次性发送全部答案无法证明多轮 checkpoint 和换任务恢复机制。

中断恢复 05

STEP 05

关闭原任务，在新任务中恢复需求

证明项目状态保存在仓库中，而不是只存在原聊天窗口里。

本步使用的 Skill / 协议 project-task-router + dgj2-validation-project-maintainer

新建任务，只发送这一段

继续 REQ-EVAL-DGJ-A。

不要读取旧聊天；请从总入口路由到对应项目，按项目协议恢复当前状态。
告诉我：
1. phase、status、Revision；
2. 已确认规则和已完成事项；
3. 剩余问题与 blocker；
4. 下一步动作。

暂时不要写文件。

Agent 应自动执行或等价读取

python3 doc/ai/scripts/resume_prd.py REQ-EVAL-DGJ-A
sed -n '1,240p' doc/ai/changes/active/REQ-EVAL-DGJ-A*/handoff.md
sed -n '1,200p' doc/ai/active-tasks.md

本步会新增或更新的产物

本轮不新增业务文件
从 active-tasks 定位需求包
从 planning-state 恢复 Revision
从 handoff 恢复已确认事项和下一步
从 events 复核关键决策来源

怎样算本步通过

新任务能准确说出最新 Revision 和五条规则，无需重新粘贴 PRD-A 或历史聊天。

现场注意： 这是验证可恢复性的关键步骤。若 Agent 要求重新解释全部需求，说明项目入口、活动索引或 handoff 仍不完整。

设计收敛 06

STEP 06

完成规划校验并沉淀可复用经验

把本次需求状态与长期项目经验分层保存：任务细节留在 change package，验证后的稳定规则进入项目知识或 Skill。

本步使用的 Skill / 协议 continuous-skill-harvester + project entry Skill

设计确认完成后发送

REQ-EVAL-DGJ-A 的产品规则已经确认完毕。

请：
1. 收敛到 design-ready；
2. 检查 R-ID → D-ID → T-ID → TC-ID 可追踪关系；
3. 执行规划和项目 AI 校验；
4. 审计本次知识沉淀；
5. 将已验证、未来同类 PRD 会复用的规则放入正确的项目文档、现有 Skill/reference，或经验候选；
6. 一次性 ID、临时数据和未验证假设不得晋级为长期经验；
7. 当前仍不修改业务代码、不部署。

收敛与知识基线

cd /Users/zhoujiangbin/code/ai-skill-validation-20260728/dgj2.0
python3 doc/ai/scripts/validate_planning.py REQ-EVAL-DGJ-A
python3 doc/ai/scripts/audit_knowledge_harvest.py
python3 doc/ai/scripts/validate_ai_system.py
git diff --stat

git add AGENTS.md .agents doc/ai
git commit -m "docs: persist PRD-A planning and reusable project knowledge"
DGJ_A_KNOWLEDGE_SHA=$(git rev-parse HEAD)

本步会新增或更新的产物

完整 change package：保留本需求上下文
项目事实/领域文档：保存稳定业务结论
现有 Skill 或 reference：保存可执行规则
experience-candidates.yaml：保存待更多证据的候选
knowledge-harvest 审计：证明没有遗漏沉淀判断
DGJ_A_KNOWLEDGE_SHA：PRD-B 实验组起点

怎样算本步通过

validate_planning、audit_knowledge_harvest、validate_ai_system 全部 PASS；知识条目能回溯到 PRD-A 证据。

现场注意： 不是每次都新建 Skill。优先更新 change package 和现有项目知识；只有稳定、可执行、重复出现的流程才晋级为 Skill。

核心实验 07

STEP 07

用完全相同的 PRD-B 对比有无经验

证明“自动发现经验”带来的不是泛泛感觉，而是旧规则命中更多、重复问题更少，同时仍能发现真正新增的阻断。

本步使用的 Skill / 协议 project-task-router + prd-to-implementation-delivery

对照组和实验组都发送完全相同内容

这是 PRD-B 设计计划验证。

要求：
1. 从总入口自动路由项目并加载项目当前有效知识；
2. 创建可恢复 change package；
3. 先查真实代码和历史规则；
4. 已有规则直接引用证据，不重复让产品确认；
5. 真正新增或冲突的问题必须提出；
6. 当前不改业务代码、不部署。

需求编号：REQ-EVAL-DGJ-B
目标项目：DGJ2

以下是 PRD：
【粘贴 demo/inputs/dgj2/03_prd_b.md 的完整正文】

分别运行两个隔离分支

# 无 PRD-A 知识的对照组
git -C /Users/zhoujiangbin/code/ai-skill-validation-20260728/dgj2.0 \
  checkout -B codex/eval-dgj2-prd-b-control 272bea0636

# 有 PRD-A 知识的实验组
git -C /Users/zhoujiangbin/code/ai-skill-validation-20260728/dgj2.0 \
  checkout -B codex/eval-dgj2-prd-b-learned "$DGJ_A_KNOWLEDGE_SHA"

本步会新增或更新的产物

对照组：从初始化基线生成 PRD-B change package
实验组：从 PRD-A 知识提交生成 PRD-B change package
两组各自的新任务聊天记录
两组首次问题、错误假设、规则命中与规划结果

怎样算本步通过

两组使用相同模型、相同 PRD-B、全新任务；唯一变量是分支是否包含 PRD-A 知识。

现场注意： 实验组不能提示 FS-LIMIT 规则名，也不能读取 gold 文件。否则无法证明 Agent 是自动发现经验。

结论与推广 08

STEP 08

按金标准评分，再用 SAAS 复验

用可量化指标判断体系是否有效，并排除“只对 DGJ2 某个活动需求有效”的偶然性。

本步使用的 Skill / 协议 项目校验脚本 + 人工评分表

两组完成后发送评分要求

请基于两组实际输出填写 PRD-B 经验复用评分表。

评分证据：
1. 两组聊天中的首次问题和用户纠偏轮次；
2. 两组 change package；
3. demo/inputs/dgj2/04_prd_b_gold.md；
4. demo/scorecard-template.md；
5. 规划校验结果。

请分别统计旧规则命中、必要新问题召回、重复确认、错误假设、
关键场景遗漏、到 design-ready 的轮次和跨任务重复解释次数。
不要只给主观结论。

评分文件与 SAAS 复验材料

ROOT=/Users/zhoujiangbin/code/ai-skill-validation-20260728

sed -n '1,240p' "$ROOT/demo/scorecard-template.md"
sed -n '1,240p' "$ROOT/demo/inputs/dgj2/04_prd_b_gold.md"

# DGJ2 结论成立后，按同一流程替换为：
# saas/01_prd_a.md、02_prd_a_corrections.md、
# 03_prd_b.md、04_prd_b_gold.md

本步会新增或更新的产物

完成版 scorecard：对照组与实验组并排
旧规则命中率与必要新问题召回率
重复确认、错误假设、遗漏和用户轮次
项目入口/路由/Skill 的失败项与改进项
SAAS 独立复验结果

怎样算本步通过

实验组减少重复确认和用户轮次，同时必要新问题召回不下降、错误假设不增加；SAAS 能复现相同趋势。

现场注意： 最终结论应说明实验条件和边界，不只说“问题从 N 个降到 M 个”。

CONTROLLED EXPERIMENT

对照实验到底在比较什么

两组必须使用相同模型、相同输入、相同旧代码和全新任务。只有“是否带有 PRD-A 沉淀经验”可以不同。

CONTROL 无经验对照组

从 DGJ2 初始化提交 272bea0636 创建分支。
创建全新任务并发送 PRD-B。
记录首次问题、错误假设、遗漏和达到 design-ready 的轮次。
不允许读取 PRD-A 结果或评分金标准。

VS 唯一变量
PRD-A 知识

LEARNED 有经验实验组

从 DGJ_A_KNOWLEDGE_SHA 创建分支。
创建另一个全新任务，发送完全相同的 PRD-B。
不提示 FS-LIMIT 规则名，让 Agent 自己从项目入口发现。
验证旧规则是否自动命中，同时真正新问题是否仍被提出。

PASS / FAIL

验证这套体系是否真的有效

不能只看 Agent 说了“我已经复用经验”。要比较规则召回、问题质量、对话轮次和可恢复证据。

指标	无经验对照组	有经验实验组	通过标准
旧规则命中率	从代码重新推断，可能漏掉或重复问	自动命中 FS-LIMIT-001～005	实验组命中率更高
重复确认数	可能再次确认保存、提交、sid、失败策略	已有规则直接引用项目证据	实验组更少
必要新问题召回	需要发现失败返回和 sid 来源	仍必须发现同样的新问题	实验组不得下降
到 design-ready 轮次	需要重新建立旧规则	只确认本次真正新增内容	实验组更少
跨任务恢复	依赖重新解释	active index + handoff + events 恢复	无需粘贴旧聊天
计划质量	可能遗漏 API 契约或旧链路边界	规则与代码证据共同约束计划	校验通过且错误不增加

ARTIFACT MAP

演示过程中应该展示哪些文件

文件变化就是链路发生过的证据。总入口负责项目发现，项目稳定知识负责复用，change package 负责恢复，交付文件负责证明结果。

总入口产物

project-registry/projects.yaml
project-registry/onboarding-report.{md,json}
cross-project/active-tasks.{md,yaml}
.agents/skills/project-task-router
.agents/skills/project-skill-initializer

项目稳定知识

AGENTS.md
doc/ai/index.md
doc/ai/project/project.yaml
doc/ai/skills/
doc/ai/contracts/ 与 runbooks/

需求过程状态

doc/ai/changes/active/<REQ-ID>/
planning-state.yaml
events/EVT-*.yaml
handoff.md
active-tasks.{md,yaml}

交付与验证证据

delivery.yaml
test-report.md
knowledge-harvest 审计
scorecard-template.md 完成版
PRD-B control / learned 对照结果

你接下来从哪里开始

要完整演示，从步骤 01 的空注册表分支开始；要重点验证经验复用，保留固定初始化基线，直接从步骤 03 的 PRD-A 开始。DGJ2 跑通后再执行 SAAS，证明不是单项目特例。

完整演示：从初始化开始适合第一次向同事讲整个体系快速实验：从 PRD-A 开始适合验证经验沉淀与轮次下降返回体系架构讲解理解总入口、项目入口与经验回流