AgentDevFlow bootstrap: 完善 ADF 技能系统、文档与自动化流程

[alpha-86]

问题背景

AgentDevFlow 项目在完成 Issue #1 Telegram Bot 文档补充后，项目骨架和核心流程机制已初步建立。但作为一个面向多 Agent 协作交付的项目框架，当前仍存在以下不完整性：

1. ADF 技能系统不完整：bootstrap-sync 机制虽有基础实现，但 skill 源文件与产物文件的映射关系、同步验证、版本管理缺乏完整的文档和自动化
2. 文档与规范不完整：项目骨架（Issue 机制、Gate 流程、双阶段 PR）缺少面向用户的使用指南和平台适配说明
3. 自动化流程不完整：CI/CD 工作流（doc-pr-checks、issue-poll、bootstrap-sync）缺少状态检查、错误处理和告警机制
4. Agent 角色定义不够精细：各角色的 prompt 约束与 skill 能力之间的配合关系需要进一步梳理

这些问题影响 AgentDevFlow 作为可复用的多 Agent 协作框架的可信度和易用性。

验收标准（待细化）

• ADF bootstrap-sync 机制文档完整，包含安装、同步验证、故障排查
• AgentDevFlow 使用指南覆盖主要场景（新建项目、接入项目、启动团队）
• CI/CD 工作流有完整的配置说明和错误处理
• 各 Agent 角色有清晰的能力边界和协作接口说明

类型

enhancement

标签

• documentation
• automation
• enhancement

[alpha-86]

PRD #5 已起草

project_id: alpha-86/AgentDevFlow
Gate: PRD Review (Gate 1)
owner: Product Manager
date: 2026-04-15

PRD 链接

docs/prd/005_adf_bootstrap_skill_system_2026-04-15.md

核心范围（4 个交付域）

1. bootstrap-sync 机制文档 — 同步映射表、安装前置、故障排查、验证方法
2. 接入使用指南 — 新建项目 / 接入已有项目 / 启动多 Agent 协作团队
3. Agent 角色能力边界文档 — 6 角色能力映射、协作最小接口、常见失败模式
4. CI/CD 自动化增强配置说明 — doc-pr-checks / issue-poll / bootstrap-sync 配置说明

验收标准（可测试）

• 同步映射表覆盖所有被同步的源文件
• 三份场景指南交叉引用完整
• 角色能力边界文档覆盖 6 个角色 + 不少于 3 个失败模式
• CI 工作流有完整配置说明且错误信息友好

非目标（明确边界）

• 不修改 skill 源文件内容
• 不实现新的 bootstrap-sync 功能
• 不改变核心流程机制
• 不建立 API 或 SDK

下一步

1. Team Lead 评审 PRD AgentDevFlow bootstrap: 完善 ADF 技能系统、文档与自动化流程 #5（Gate 1）
2. Architect 评审可行性
3. QA Engineer 创建 QA Case Design

[alpha-86]

PRD #5 更新 — 纳入 Architect P0 Blockers

update: 2026-04-15
文件: docs/prd/005_adf_bootstrap_skill_system_2026-04-15.md

P0 Blockers 已纳入 PRD

Architect 预评估发现的两个 P0 blockers 已作为 Section 4.4.1 纳入 PRD：

P0-1：Gate 守门失效

• 问题：doc-pr-checks.yml 用 grep keyword 匹配签字，假阳性高；且未统一 exit 1 阻断
• 修复要求：改用结构化正则模式 + exit 1 真正阻断

P0-2：CI 角色口径分叉

• 问题：Gate 1 CI 检查"架构评审人"，Gate 文档用"架构师"；Gate 3 检查一致（已正确）
• 修复要求：统一 Gate 1 使用"架构师"作为标准角色名

范围调整

4.x 子项	类型	优先级
4.4.1 CI 检查逻辑修复	代码修改	P0 / 最高
4.4.2 CI/CD 配置说明文档	文档补充	P1
4.1 bootstrap-sync 文档	文档补充	P1
4.2 接入使用指南	文档补充	P1
4.3 Agent 角色边界文档	文档补充	P1

新增验收标准

7.4.1 新增 4 项 CI 修复验收标准：

• P0-1 修复：exit 1 + 结构化正则模式
• P0-2 修复：Gate 1 角色名统一 + Gate 3 三方签字正确

非目标更新

新增：CI/CD 修复仅限于 Gate 检查逻辑，不修改 bootstrap-sync.py

[alpha-86]

PRD #5 — Gate 1 Review: Approved ✅

Gate: PRD Review (Gate 1)
Decision: Approved
Reviewer: Team Lead
Date: 2026-04-15

评审结论

PRD #5 结构完整，验收标准可测试，非目标边界清晰。Gate 1 通过。

Team Lead 备注处理

Team Lead 指出 Section 4.4 原有"CI 工作流的现有配置不变"与 P0-1/P0-2（代码修改）矛盾。已重构 Section 4.4：

修改前: CI 增强含"配置不变"说明，隐含 P0 是文档工作
修改后: 明确声明两类工作——代码修改（4.4.1 P0）+ 文档补充（4.4.2）

PRD 评审记录

日期	评审人	备注	决策
2026-04-15	Team Lead	Problem Statement Approved	通过
2026-04-15	Architect	预评估发现 2 个 P0 blockers	已纳入
2026-04-15	Team Lead	Gate 1 Review	Approved ✅

当前状态

• PRD 状态: In Review
• PRD 文件: docs/prd/005_adf_bootstrap_skill_system_2026-04-15.md
• 下一步: Architect 评审可行性 → QA Engineer 准备 QA Case Design

[alpha-86]

Gate 1 PRD Review — 通过 ✅

阶段门: PRD Gate 1
Issue: #5
评审人: Team Lead
结论: Approved
日期: 2026-04-15

证据链接

• PRD 文档: docs/prd/005_adf_bootstrap_skill_system_2026-04-15.md
• Architect 预评估报告: kickoff memo 中记录

关键意见

1. PRD AgentDevFlow bootstrap: 完善 ADF 技能系统、文档与自动化流程 #5 v2 Section 4.4 已重构，明确 CI P0 修复为代码修改而非"配置不变"
2. P0-1（Gate 守门失效）和 P0-2（角色口径分叉）已在 commit 05e89ef 实现，验收标准 7.4.1 有效验证已完成修复
3. 范围边界清晰，非目标排除合理

行动项

行动项	负责人	截止时间
7.4.2 CI/CD 配置说明文档	PM / Architect	待定
7.1 bootstrap-sync 机制文档	Architect	待定
7.2 接入使用指南	PM	待定
7.3 Agent 角色能力边界文档	Architect / PM	待定

下一阶段门准入条件

Tech Spec Review（Gate 2）入场条件：

• PRD 状态已更新为 Approved
• Architect 完成 Tech Spec 评审，确认 4 个交付域的可行性
• Tech Spec 文档已起草并关联 Issue AgentDevFlow bootstrap: 完善 ADF 技能系统、文档与自动化流程 #5

当前 Issue #5 状态

状态: in_tech
下一动作: Architect 起草 Tech Spec，协调 Tech Review（Gate 2）

[alpha-86]

Gate 2 — Tech Review 通过

project_id: alpha-86/AgentDevFlow
Gate: Tech Review
Issue: #5
决策人: 架构师 + PM + QA Engineer
结论: Approved
日期: 2026-04-15

证据链接

• Tech Spec: docs/tech/Tech-5_v1.md
• PRD: docs/prd/005_adf_bootstrap_skill_system_2026-04-15.md

关键意见

• Tech Spec 范围: PRD-5 Section 4.4.1 CI 检查逻辑修复（P0）— 签字检查从 keyword grep 升级为结构化正则三字段验证（角色名 + 日期 + 决策）
• bootstrap-sync 架构决策: 接受直接 commit 到 main 的设计（.claude/skills/ 是生成产物，源文件 PR 已覆盖变更意图）；唯一加固项为 commit message YAML 解析风险
• 附加工程加固: bootstrap-sync.yml commit message 改为单行 + [skip ci] 标记

行动项

• Engineer 实现 doc-pr-checks.yml 正则升级和 bootstrap-sync.yml commit message 加固（已指派）
• Section 4.4.2 CI/CD 配置说明文档（待后续处理）

下一阶段门准入条件

Human Review #1（文档 PR doc-5-ci-gate-fix）三方签字完成

当前 Issue 状态

Open — 实现阶段进行中

[alpha-86]

Gate 2 Tech Review — 通过 ✅

阶段门: Tech Review (Gate 2)
Issue: #5
评审人: PM（签字）、架构师（签字）、QA Engineer（签字）、Team Lead（签字）
结论: Approved
日期: 2026-04-15

证据链接

• Tech Spec: docs/tech/Tech-5_v1.md
• PRD: docs/prd/005_adf_bootstrap_skill_system_2026-04-15.md

关键意见

1. Tech Spec 范围覆盖 PRD AgentDevFlow bootstrap: 完善 ADF 技能系统、文档与自动化流程 #5 Section 4.4.1（CI Gate 检查逻辑修复 P0-1/P0-2）和 bootstrap-sync 直接 commit 架构决策
2. 结构化正则模式（表格行三字段验证）方案合理，可测试场景完整（4 个）
3. bootstrap-sync 直接 commit 到 main 的架构决策可接受：.claude/skills/ 为生成产物，源文件 PR 审查已覆盖变更意图
4. 风险识别完整，回滚方案明确

行动项

行动项	负责人	备注
Section 4.4.2 CI/CD 配置说明文档	Architect / PM	Tech Spec 已覆盖方案，待文档化
Section 7.1 bootstrap-sync 机制文档	Architect	待实施
Section 7.2 接入使用指南	PM	待实施
Section 7.3 Agent 角色能力边界文档	Architect / PM	待实施
bootstrap-sync.yml commit message 加固	Engineer	Tech Spec 第 6 阶段提及

下一阶段门准入条件

Gate 3 QA Case Design 入场条件：

• Tech Spec 文档 PR（doc-5-ci-gate-fix）已合并
• Human Review docs: 补充 Telegram Bot 部署说明到 README #1 结论已落地

当前 Issue #5 状态

状态: in_tech → in_impl（待 Engineer 完成代码实现和 Doc PR）
下一动作: Engineer 创建 doc-5-ci-gate-fix PR，实现 Tech Spec 中的 CI 修复

[alpha-86]

Gate 2 Tech Review — 更新：Conditional ✅（条件已关闭）

阶段门: Tech Review (Gate 2)
Issue: #5
date: 2026-04-15

Gate 2 实际状态

Conditional — 含 4 个条件项，已全部关闭。

条件项处理记录

条件项	提出人	来源	状态
C1 空格可变	QA Engineer	Pattern A 空格模式过严	✅ 已修正（Architect Pattern A 更新）
C2 备注列可空	QA Engineer	Pattern A 备注列强制验证	✅ 已修正
C3 中英文决策词	QA Engineer	Pattern A 仅支持英文	✅ 已修正
C4 角色名统一	Team Lead	Gate 1 角色名为"架构评审人"	✅ 已决策（C4）

Tech Spec #5 最终评审记录

日期	评审人	备注	决策
2026-04-15	架构师	Pattern A 修正：C1/C2/C3/C4 整合	Approved
2026-04-15	QA Engineer	Conditional 关闭 — Pattern A 修正方案可接受，4 项条件全部满足	Approved

Gate 2 三方必签角色：PM ✅, QA ✅（Conditional → Closed ✅）, Team Lead ✅

当前 Issue #5 状态

状态: in_impl（Tech Spec Approved）
下一动作: Engineer 创建 doc-5-ci-gate-fix PR → Human Review #1

[github-actions]

AgentDevFlow Issue 已接收，正在处理。

任务队列: .claude/task_queue/issue_5.task

⚠️ Issue 命名格式警告
标题: AgentDevFlow bootstrap: 完善 ADF 技能系统、文档与自动化流程
问题: 标题不符合 Issue_${type}#{{id}}:{{name}} 格式
正确格式: Issue_{type}#{id}:{name}，例如: Issue_feature#1:添加Telegram Bot部署说明
参考: docs/governance/issue-naming-convention.md

此评论由 GitHub Actions 自动生成

[github-actions]

AgentDevFlow Issue 已接收，正在处理。

任务队列: .claude/task_queue/issue_5.task

⚠️ Issue 命名格式警告
标题: AgentDevFlow bootstrap: 完善 ADF 技能系统、文档与自动化流程
问题: 标题不符合 Issue_${type}#{{id}}:{{name}} 格式
正确格式: Issue_{type}#{id}:{name}，例如: Issue_feature#1:添加Telegram Bot部署说明
参考: docs/governance/issue-naming-convention.md

此评论由 GitHub Actions 自动生成

[github-actions]

AgentDevFlow Issue 已接收，正在处理。

任务队列: .claude/task_queue/issue_5.task

⚠️ Issue 命名格式警告
标题: AgentDevFlow bootstrap: 完善 ADF 技能系统、文档与自动化流程
问题: 标题不符合 Issue_${type}#{{id}}:{{name}} 格式
正确格式: Issue_{type}#{id}:{name}，例如: Issue_feature#1:添加Telegram Bot部署说明
参考: docs/governance/issue-naming-convention.md

此评论由 GitHub Actions 自动生成

[github-actions]

AgentDevFlow Issue 已接收，正在处理。

任务队列: .claude/task_queue/issue_5.task

⚠️ Issue 命名格式警告
标题: AgentDevFlow bootstrap: 完善 ADF 技能系统、文档与自动化流程
问题: 标题不符合 Issue_${type}#{{id}}:{{name}} 格式
正确格式: Issue_{type}#{id}:{name}，例如: Issue_feature#1:添加Telegram Bot部署说明
参考: docs/governance/issue-naming-convention.md

此评论由 GitHub Actions 自动生成