Coding Agent Harness

--- name: coding-agent-harness description: > Coding Agent Harness 工程方法论。为使用 Coding Agent（Codex、Claude Code、Gemini CLI 等） 做长程项目开发的团队，在用户的项目上构建一套完整的 harness 工程体系。 包括：项目诊断、AGENTS.md + CLAUDE.md 入口文件生成、coding-agent-harness/ 目录搭建、Planning Loop、SSoT 治理、 Delivery Operating Model、Repository Governance、CI/CD、Long-Running Task Protocol、Adversarial Review Report、Review Routing、Worktree 并行开发、 Regression SSoT 与 Evidence Depth 分级回归、Walkthrough / Closeout Index 收口、Cadence Ledger、任务本地 lesson 候选与 promoted lesson 详情文档、 Harness Ledger 全局上下文回写总账。 当用户要求设置 coding agent 的开发流程、建立回归测试体系、设计 AGENTS.md / CLAUDE.md、 规划长程 agent 任务的执行框架、子代理审查循环、对抗性 review 报告、搭建 harness、或者提到 harness engineering 时，使用此技能。 也适用于"帮我搭一套 agent 开发规范"、"怎么让 AI 在长任务上不跑偏"、 "怎么做 agent 的回归测试"、"帮我初始化项目的 harness"等场景。 --- # Coding Agent Harness 工程方法论 一套经过真实项目验证的方法论，用于在任意项目上构建 Coding Agent 的工程化支撑体系。 ## 核心理念 - **文档是写给 Agent 看的，不是写给人看的。** 人看排期表、架构文档和执行 output。Agent 看 task_plan、walkthrough、reference 标准。 - **上下文不是越多越好，是越准越好。** AGENTS.md 做目录不做百科；CLAUDE.md 只做 Claude Code 兼容 shim，不做第二份规范。 - **单元测试只是底线，不是保障。** 真正的保障需要多层证据（Evidence Depth）。 - **先识别交付组织，再设计 harness。** 一人多 agent、多人团队、前后端分仓、program 多仓、敏捷/瀑布，对应的 SSoT 和冲突治理不同。 - **Repo 护栏是地基。** CI/CD、PR policy、branch protection、required checks、worktree concurrency 必须项目级定制，不能停留在模板。 - **外部资料先摄取，再投影。** 微服务或多仓项目的外部文档不能直接塞进执行文档；先建 source pack、digest、验证，再投影到 `context/{architecture,development,integrations}`。 - **长程任务先设计合同，再开放执行。** 连续跑数小时的前提是 Goal、Scope、Review Loop、Evidence、Stop Condition 都清楚。 - **审查必须落盘。** 对抗性 review 是独立交付物，不应只留在对话、progress 或 walkthrough 里；reviewer 必须用 Confidence Challenge 反复挑战方案，直到没有 open material finding。 - **Worker handoff 必须 commit-backed。** 可写 subagent 不是 reviewer；它必须在独立 worktree / branch 内实现、验证并提交，再由 coordinator 集成。 - **严肃项目用顶级模型。** 便宜模型的返工成本远高于差价。 - **强制流程优于口头约定。** 每个步骤都应该是 agent 可自主执行的。 ## Product Contract Full Harness 与后续 Lite Skill 的共享任务语义由 Document Contract Kernel 约束，公开源位于 `docs-release/architecture/document-contract-kernel/README.md`。 凡是改变 AGENTS、context、task package、progress、walkthrough、review、 regression 或 lessons 基础语义的改动，必须按该 contract 同步 Full/Lite overlay 与 compatibility matrix；Full-only 的 CLI、Dashboard、Preset、 generated ledger、Module Registry、lifecycle command、runtime requirement 不得泄漏进 Lite source。 --- ## 主执行 SOP 如果用户要求"更新 harness"、"同步最新版 harness"、"把项目升级到最新 coding-agent-harness"，不要重新 bootstrap 覆盖整个项目。先执行增量更新流程： 1. 读取本 Skill 的最新版 `SKILL.md`、相关 `references/`、`templates/`。 2. 扫描目标项目现有 `AGENTS.md`、`CLAUDE.md`、`coding-agent-harness/` 和 SSoT / Ledger 文件。 3. 输出 delta plan：哪些 harness 骨架、reference、template、SSoT、Ledger 项缺失或过期。 4. 只补齐新增标准和缺失结构；不得用模板覆盖已有业务事实、历史 walkthrough、 task progress、generated ledger、Regression SSoT 或 lesson detail docs。 5. 对已有文档采用 merge / append / residual-with-reason；只有全新缺失文件才从模板创建。 6. 如果引入 Harness Ledger、lesson detail docs 或新的 reference/template，同步更新入口索引。 7. 收口时写 walkthrough，必须包含 Lessons Reflection；新任务先写并审查 `lesson_candidates.md`。如人工标记值得沉淀，默认先用 dry-run 或后续 lesson sedimentation 任务完成分类、冲突检查和建议 diff；只有人工明确批准后， 维护命令才写 `coding-agent-harness/governance/lessons/` 详情文档；最后在 `coding-agent-harness/governance/generated/Harness-Ledger.md` 与 `coding-agent-harness/governance/generated/Closeout-Index.md` 记录本次 harness update 的 delta 和 Lessons Check。 一句话：harness update 是 delta merge，不是重新搭一遍。 当用户要求在项目上搭建 harness 时，使用 v1.0 的六阶段安装流程。安装不是 `npm install` 式复制文件，而是 CLI scaffold 与 Agent configure 配合完成。 面向 agent 的详细安装和迁移说明见 `docs-release/guides/agent-installation.md`。如果本 Skill 与该指南出现差异，以 本 Skill 的执行约束为准，并把差异记录为需要修复的文档漂移。 CLI 示例默认使用目标项目可调用的 `harness` 命令。执行前先检查 `command -v harness`；如果没有，不要静默全局安装，按安装指南询问用户是否 允许 `npm install -g coding-agent-harness`。未获明确同意时，用 `npx --yes coding-agent-harness ` 执行同一条命令。只有维护本源码 checkout 时，才把 `harness` 替换为 `node dist/harness.mjs`；源码仓的 `dist/` 是生成物，若不存在先运行 `npm install` 或 `npm run build:runtime`。 ### Agent 安装合同 这个 CLI 的主要操作者通常是目标项目里的 agent，而不是最终用户。Agent 不应要求用户 记命令、读模板目录或手动判断 locale；这些决策必须由 agent 在安装流程中完成。 - 交互式安装：如果用户在场，agent 必须先确认文档语言，再运行 `harness init --locale zh-CN|en-US --capabilities ...`。也可以让 CLI 交互提问， 但 agent 仍要在收口说明中写明最终选择。 - 非交互式安装：agent 不得依赖 CLI 的 `en-US` 默认值；必须从用户语境、项目语言或 明确配置中推断 locale，并显式传 `--locale`。如果无法判断，先暂停询问。 - 中文用户或中文项目默认选择 `zh-CN`；英文团队、英文代码库或用户明确要求英文时选择 `en-US`。 - scaffold 后必须检查 `coding-agent-harness/harness.yaml` 的 `locale`，并确认 dashboard、 task template、review template 来自同一套模板树。 - `templates/` 和 `templates-zh-CN/` 是两套完整模板树。不要在目标项目里混拷两套模板； 只允许保留 schema 字段、文件名、状态枚举、命令和跨工具协议 token 的英文。 - 如果只是 dogfood 测试，默认清理目标项目里的测试产物，不提交。 ### Phase 1: Diagnose / 项目诊断 读 `references/project-onboarding-audit.md`，扫描项目技术栈、目录结构、现有文档、 CI、团队/agent 协作方式和风险面，输出诊断报告。 如果发现项目属于微服务、多仓、前后端分仓、平台子系统，或代码中出现外部服务、 SDK、API gateway、message queue、webhook、contract、schema、mock，必须询问用户是否有 外部资料。问题至少覆盖：是否有外部团队文档、接口文档、架构图、会议纪要、链接或导出包； 这些资料能否复制进仓；哪些资料是可信来源。外部资料处理方法见 `references/external-source-intake-standard.md`。 ### Phase 2: Decide / 方案决策 与用户确认三件事： 1. 文档语言：`zh-CN` 或 `en-US`。中文用户默认应获得中文任务、评审、 ledger、SSoT、walkthrough 和 reference draft。 2. Delivery Operating Model：solo-orchestrator、team-feature-lead、 split-repo-contract、program-multi-repo、waterfall-stage-gate 或 kanban-continuous。 3. Capability Packs：core 必装；按需选择 module-parallel、subagent-worker、 adversarial-review、long-running-task、dashboard。旧项目先用 `migrate-structure --plan/--apply` 迁到 v2，不再通过兼容 capability 长期运行。 4. External Source Intake：如果外部资料超过 5 份、跨多个主题或会持续增长， 决定是否创建 `coding-agent-harness/context/development/external-source-packs//`。 Capability 选择规则必须按表执行，不得凭感觉多装： | Capability | 何时选择 | | --- | --- | | `core` | 永远安装。它是任务计划、回归、walkthrough、Lessons 和 Harness Ledger 的最小内核。 | | `dashboard` | 用户或 agent 需要本地只读状态页时安装。它不写目标项目文件。 | | `adversarial-review` | 发布、架构、安全、数据、策略风险需要独立 review artifact 时安装。 | | `long-running-task` | 用户允许 agent 多轮连续执行、不能每步都询问时安装。 | | `module-parallel` | 项目有 2 个以上可独立演进模块，且需要模块 owner / registry / 同步规则时安装。 | | `subagent-worker` | 会改代码的 subagent 需要独立 worktree + commit-backed handoff 时安装；它依赖 `module-parallel`。 | 如果选择了某个可选 capability，bootstrap summary 必须写清触发它的项目事实。 ### Phase 3: Scaffold / 脚手架 运行或模拟 `harness init --locale zh-CN|en-US --capabilities ...`。面向 agent 的安装 必须显式传 `--locale`；只有人直接在终端运行且未传 `--locale` 时，CLI 才交互询问。CLI 只创建 目录、模板、空表、索引和 `coding-agent-harness/harness.yaml`，不得把项目级 reference 伪装成已经定制完成的标准。 CLI 会在 JSON 输出中返回 `report`。Agent 必须读取这份 report，并把其中的 `locale`、`selectedCapabilities`、`created/skipped`、`agentInstructions` 和 `verificationCommands` 转化为交付 summary；不能只看命令退出码。 ### Phase 4: Configure / 对话式定制 Agent 根据项目事实与用户讨论后定制 AGENTS.md、reference standards、CI/CD、 Regression surface、Delivery SSoT、Module Registry、review routing 和 worktree/subagent handoff 规则。已有项目事实只能 merge/append/residual， 不能模板覆盖。 如果用户提供了外部资料，Configure 阶段必须按 `external-source-intake-standard.md` 执行：Inventory、Classify、Sanitize、Digest、 Project、Verify、Residual。`external-source-packs/` 只保存资料索引、摘要和投影状态； 稳定事实必须回写到 `coding-agent-harness/context/architecture`、`coding-agent-harness/context/development/external-context` 或 `coding-agent-harness/context/integrations`。 ### Phase 4b: Task Lifecycle / 任务生命周期 初始化或迁移完成后，活跃任务必须通过 CLI 创建和推进，避免 agent 手工复制模板造成漂移： ```bash harness new-task --title "