xuanbingbingo/claude-agent-dev-team/agent-dev-team

docs/
  CAPABILITY_PROFILE.md   ← ★核心契约★ 场景识别→能力画像（architect 主笔，eval-lead 共同定稿）
  AGENT_SPEC.md           ← agent 系统架构（选型/编排/模型/context/memory）architect
  EVAL_SPEC.md            ← ★核心契约★ eval 数据集/断言/成功指标/红线场景 eval-lead
  PROMPT_SPEC.md          ← system prompt / 角色设定 / 输出结构 builder
  TOOL_CONTRACT.md        ← 工具/function 定义（名/参数/返回严格约束）builder
  RAG_SPEC.md             ← 仅当能力画像标注"需外部知识"才生成 builder
  TRACE_SPEC.md           ← 可观测性：每步 trace 必须记录的字段 runtime
  RUNTIME_STATUS.md       ← runtime 实现中发现的契约歧义上报（类比 BACKEND_STATUS）
  EVAL_REPORT.md          ← ★每轮迭代 eval 结果累计★（类比 QA_REPORT，eval-lead 追加写）
  SAFETY_REPORT.md        ← 安全审查报告 safety
  ACCEPTANCE_REPORT.md    ← 最终验收报告 reality-checker
agent-tasks/
  build-tasklist.md       ← 构建任务清单（能力单元维度，非接口维度）
  iteration-log.md        ← ★每轮循环日志★：改了什么 → eval 指标变化 → trace 定位到的根因

输入：现有 agent 源码 / prompt / 工具定义 / 线上 trace 或对话日志（用户提供）
architect 产出：docs/CAPABILITY_PROFILE.md（逆向标注：实际是什么场景、上了哪些能力、有无过度设计）
eval-lead 产出：docs/EVAL_REPORT.md 的"缺口诊断"章节，重点回答：
  - 这个 agent 有没有 eval？没有 → 这是头号病根
  - 现有失败案例归类：任务失败 / 工具调错 / 幻觉 / 越权 / 成本失控，各占多少
  - 有没有 trace？没有 trace → debug 全靠猜，是第二病根

输入：agent 源码 + 工具定义 + 系统 prompt
重点：prompt injection 面、工具越权面、系统 prompt 泄露、敏感数据外泄
产出：docs/SAFETY_REPORT.md

🔍 Agent 应用 Audit 完成：{名称}
 
🧭 场景画像：{单/多 agent、workflow-vs-agent 是否选对、有无过度设计}
🔴 头号病根：[通常是"没有 eval"或"没有 trace"]
🟡 失败模式分布：任务失败 x% / 工具调错 x% / 幻觉 x% / 越权 x% / 成本 x%
🔒 安全：注入面 / 越权面 / 泄露面
➡️ 建议动作：[先补 eval → 再补 trace → 才谈优化]

mkdir -p docs agent-tasks

architect 输入：用户原始需求
architect 动作：走内置的"场景识别决策树"（5 个判定维度），逐维判定后输出能力画像
architect 产出：docs/CAPABILITY_PROFILE.md，必须包含：
  - 5 维判定结果：
      ① 知识依赖：要不要外部知识/私有数据 → 决定上不上 RAG
      ② 自主度：固定步骤能解决 vs 需模型自主决策多步 → 决定 workflow 还是 agent
      ③ 副作用：有没有写操作/花钱/发消息/改数据 → 决定 safety 权重与审批门
      ④ 记忆：要不要跨轮/跨会话记住 → 决定 memory 架构
      ⑤ 多智能体必要性：单 agent 能否胜任 → 默认单 agent，除非有硬证据要多
  - 能力清单：由 5 维推出的"本项目需要哪些能力模块"（RAG / 工具 / 记忆 / 多agent / 审批）
  - 明确 MVP 边界（✅本期 / ❌不做）
 
eval-lead 输入：architect 的能力画像草稿
eval-lead 动作：当场把能力画像翻译成"该度量哪几层"，并回填到 CAPABILITY_PROFILE 的"验收维度"章节
eval-lead 产出（回填）：CAPABILITY_PROFILE.md 的"怎么算赢 + 红线"章节：
  - 根据能力清单裁剪度量层（没 RAG 就没召回率这格；纯问答就没有工具调用层）
  - 每个能力模块对应 1-2 条可自动跑的成功断言
  - 标出"绝不能碰"的红线场景（越权、幻觉造假数据、泄露 system prompt 等）
 
完成标志：docs/CAPABILITY_PROFILE.md 存在，5 维判定齐全，验收维度已由 eval-lead 回填

architect 输入：读取 docs/CAPABILITY_PROFILE.md
architect 产出：docs/AGENT_SPEC.md
  - 编排模式（单 agent / prompt chaining / routing / 并行 / orchestrator-worker / 反思循环）
  - 模型选型（默认 Claude 最新：Opus 4.8 复杂决策 / Sonnet 5 主力 / Haiku 4.5 轻量分类），标注每个节点用哪个
  - context 架构（system prompt 骨架、上下文窗口预算、截断/压缩策略）
  - memory 架构（短期会话 / 长期记忆 / 检索式记忆，仅当画像需要）
  - 停止条件与最大步数（防止 agent 无限循环烧 token）
 
eval-lead 输入：读取 docs/CAPABILITY_PROFILE.md
eval-lead 产出：docs/EVAL_SPEC.md ← 核心契约
  - eval 数据集：覆盖 happy path + 边界 + 红线场景，每条含输入 + 期望
  - 断言方式：精确匹配 / 结构校验 / LLM-as-judge / 工具调用轨迹校验，逐条标注
  - 成功指标与达标线（如：任务成功率 ≥ 85%，越权拦截率 = 100%）
  - 红线断言（一票否决项，任何一条挂 = 不许上线）
 
关键要求：
- EVAL_SPEC 的每条 case 必须可自动跑，禁止"人工感觉一下"
- 达标线必须是数字，禁止"效果不错"这类模糊表述
- 红线项和普通指标分开写，红线是硬门

builder 输入：读取 CAPABILITY_PROFILE.md、AGENT_SPEC.md
builder 产出：
  - docs/PROMPT_SPEC.md    system prompt 全文、角色设定、few-shot、输出结构（JSON schema/格式约束）
  - docs/TOOL_CONTRACT.md  每个工具：名称、描述、参数 schema、返回结构、错误返回、调用示例
  - docs/RAG_SPEC.md       仅当画像标注"需外部知识"：chunk 策略、embedding、检索/rerank、context 拼装
  要求：
  - 工具定义严格 schema 化，参数名/类型/必填穷举，禁止"其他参数"
  - system prompt 里的角色边界、拒答规则必须与 EVAL_SPEC 红线对齐
 
runtime 输入：读取 AGENT_SPEC.md、TOOL_CONTRACT.md
runtime 产出：docs/TRACE_SPEC.md
  - 每一步必须落 trace 的字段：step、输入 context、模型输出、工具调用+参数+返回、token、耗时、失败原因
  - trace 存储与回放方式（本地 jsonl / 平台 / 自建）
  要求：trace 是 eval 和 debug 的地基，没有 trace 不许进 Phase 4

目标：搭出一个能"端到端跑通一次"的最小 agent 骨架，不求好用，只求能跑 + 有 trace
输入：PROMPT_SPEC.md、TOOL_CONTRACT.md、AGENT_SPEC.md、TRACE_SPEC.md
产出：
  - 可运行的 agent 代码（runtime 编排 + builder 的 prompt/tool 落地）
  - 至少能对 EVAL_SPEC 里 1 条 happy path case 跑出完整 trace
完成标志：跑一条 case，trace 完整落盘，能看到每一步
 
若 runtime/builder 发现契约歧义 → 写入 docs/RUNTIME_STATUS.md 的 ISSUES 章节 → 打回 architect/eval-lead

LOOP（每一轮）：
 
  STEP 1 - 调用 agentapp-eval-lead 跑全量 eval：
    输入：读取 docs/EVAL_SPEC.md，对当前 agent 跑全部 case
    产出：追加写入 docs/EVAL_REPORT.md，记录本轮：
      - 各指标数值 + 是否达标（对比上一轮，标出↑↓）
      - 红线项是否全过（任何一条挂 → 最高优先级）
      - 失败 case 清单 + 每条挂在哪一步（引用 trace）
 
  STEP 2 - 主会话读 EVAL_REPORT + 对应 trace，定位根因，判断打回谁：
      - 幻觉 / 输出不合格 / 角色跑偏      → agentapp-builder 改 PROMPT_SPEC
      - 工具调错 / 参数错 / 该调没调      → agentapp-builder 改 TOOL_CONTRACT（或 architect 调编排）
      - 检索没召回 / context 拼错        → agentapp-builder 改 RAG_SPEC
      - 编排绕路 / 死循环 / 停不下来      → agentapp-architect 改 AGENT_SPEC（编排/停止条件）
      - 崩在 runtime / trace 缺字段       → agentapp-runtime
      - 越权 / 注入 / 泄露                → agentapp-safety（红线，最高优先级）
 
  STEP 3 - 被打回的 agent 做最小改动，主会话在 iteration-log.md 记录：
      "本轮改了什么 → 预期影响哪个指标 → 下轮验证"
 
  回到 STEP 1 重新跑全量 eval（回归，确认没按下葫芦浮起瓢）
 
退出条件（同时满足才出循环）：
  ✅ EVAL_SPEC 全部红线项 = 100% 通过
  ✅ 所有成功指标 ≥ 达标线
  ✅ 最近一轮相比上轮无指标回退（无 regression）
 
止损规则：
  - 连续 3 轮某指标不升反降或原地踏步 → 暂停，向用户报告，可能是能力画像/eval 设计本身有问题，
    回 Phase 1-2 重审（这是特性不是 bug：eval 循环能暴露"需求本身没想清楚"）

输入：agent 源码、TOOL_CONTRACT.md、PROMPT_SPEC.md、若干真实 trace
重点检查：
  - Prompt injection：用户输入能否劫持 system 指令 / 篡改工具调用
  - 工具越权：agent 能否调用超出授权范围的工具 / 传入危险参数（删库、越权查询、乱发消息）
  - 数据泄露：能否套出 system prompt / 其他用户数据 / 密钥
  - 副作用护栏：写操作/花钱/发消息类工具是否有审批门或二次确认
产出：docs/SAFETY_REPORT.md
若发现高危 → 打回对应 agent 修复 → 重新扫 + 补一条 safety eval 进 EVAL_SPEC 防回归

输入：
  - 读取 docs/CAPABILITY_PROFILE.md（对照本期承诺的能力）
  - 读取 docs/EVAL_REPORT.md（最近一轮，验证达标线 + 红线）
  - 读取 docs/SAFETY_REPORT.md
  - 读取 agent-tasks/build-tasklist.md（验证能力单元全实现）
  - 亲自触发若干 EVAL_SPEC case + 至少 1 条未在 eval 集里的"新鲜"case（防过拟合 eval）
 
判决规则：
  - 默认判决：NEEDS WORK（必须有压倒性证据才能 READY）
  - READY 条件：
      ✅ CAPABILITY_PROFILE 本期能力全部实现
      ✅ EVAL_SPEC 红线 100% 通过、成功指标全部达标（有 EVAL_REPORT 证据）
      ✅ 无未修复安全高危
      ✅ 新鲜 case 也能过（没有对着 eval 集过拟合）
产出：docs/ACCEPTANCE_REPORT.md（覆盖式刷新）

产出：README.md（agent 用途、能力边界、如何跑 eval、如何加工具、模型/成本说明、部署方式）
     + docs/AGENT_CARD.md（对外的能力说明卡：能做什么、不能做什么、已知失败模式）

✅ Agent 应用构建完成：{名称}
 
🧭 场景画像：{单/多 agent}，{workflow / autonomous}，{上了哪些能力：RAG/工具/记忆/审批}
🎯 Eval 达标：{成功指标 x/y 达标}，红线 {n} 项全过
🔁 迭代轮次：{共 n 轮循环收敛}
🛠️ 工具：{已实现工具数}，全部经轨迹校验
🔒 安全：{注入/越权/泄露} 已过 safety eval，高危已清零
✅ 验收：reality-checker 判决 READY（含新鲜 case 验证，无过拟合）
📁 文档：README + AGENT_CARD 已生成
 
⚠️ 已知失败模式 / 遗留项：{诚实列出 eval 里仍偏弱但未达红线的项}