用途
agentic-harness 是一个 Claude Code 插件，用于在现有代码仓库中搭建、评估和维护一套“智能体工具链”（agentic harness）。它关注的是让仓库与 Claude Code 良好协作所需的项目本地智能体、技能和编排器，而非直接完成用户的领域工作。其目标是替代每次会话中临时拼凑的提示词，为项目构建一个专属团队，并由 Claude Code 自动路由。
主要能力
- 量身定制：生成的智能体和技能镜像仓库的技术栈、领域和任务类型，而非通用模板。
- 单一入口：编排器注册在 CLAUDE.md 中作为硬性关卡，确保每个提示都经过正确流程。
- 协调而非重复：当项目已有规范驱动系统或问题跟踪器时，编排器与其协调（激活规范、恢复交接、拉取就绪工作并写回状态），不重新实现。
- 无锁定：对于规范系统和跟踪器，仅推荐最合适的方案，并将安装委托给该工具自身的安装器。
- 可维护可追溯：对工具链的每次变更都需先批准再写入，并记录在变更历史中。
- 学习与改进：harness-review 读取仓库的重复活动和工作模式，定期向 harness-setup 提出改进建议；harness-feedback 将每次运行转化为结构化、隐私安全的反馈，用于改进工具本身。
使用方式
插件提供多个技能（skills），可通过直接调用（如 /agentic-harness:harness-setup）或由 Claude 根据上下文触发。
- harness-setup：写入者。分析项目，设计智能体团队及所用技能，生成到 .claude/，构建编排器，并在 CLAUDE.md 中注册入口指针。也可扩展现有工具链、应用评审上下文并记录变更。
- harness-review：只读。盘点工具链，检测漂移，评估技能和智能体的实际使用效果，并生成优先改进建议供 harness-setup 执行。
- harness-feedback：闭环反馈。对一次工具链运行进行回顾，按标准格式起草反馈，隐去项目标识细节，并在明确同意后向上游仓库提交 GitHub issue。可在 harness-setup 或 harness-review 运行结束时提供，或单独通过 /feedback 命令调用。
- spec-advisor：检测项目是否缺少规范驱动开发系统，并推荐最合适的方案（如 GitHub Spec Kit、OpenSpec、BMAD-METHOD、Agent OS、Taskmaster、AWS Kiro、ADR 工具），将安装委托给对应系统。离线优先，先扫描，已有系统则不介入，从不自己撰写规范。
- tracker-advisor：检测项目是否缺少适合智能体工作的问题跟踪器，推荐最合适方案（如 Beads、Backlog.md、git-bug、git-issues、Beans，或通过官方途径的 GitHub Issues / Linear / Jira），并委托安装。同样离线优先、先扫描、不自己创建问题。
- visual-advisor：选择生成的工具链使用的视觉栈：一个评审界面（如 lavish 的浏览器内标注循环、visual-explainer 或静态文件），最多两个生成器（图表、仪表盘、图像 API、设计工具），以及一个样式源。向用户介绍视觉在领域中的适用性，邀请用户提供自己的视觉模式，并呈现领域特定的利弊（包括成本、隐私、浏览器可运行性）。harness-setup 随后生成项目 {domain}-visuals 技能记录这些选择。
- harness-doctor：只读。使用确定性脚本检查机器上工具链的工具注册表所列举的内容（插件、技能、MCP 服务器、CLI、API 密钥变量），并报告为 ok、missing、disabled、stale 或 broken-link。提出固定安装行，逐项批准后由 harness-setup 执行。每个生成的工具链都会获得一个自包含的 {domain}-setup-check 技能。
组件协作
工具链循环为：review → setup → review。harness-review 读取并排序；harness-setup 写入并记录。当软件项目缺少匹配的流程层（规范系统或跟踪器）时，顾问会在循环旁提供，并始终将安装委托给所选系统。视觉不同：它是工具角色，visual-advisor 在工具发现中运行，每次构建都提供，并复用已有的视觉工具。harness-doctor 位于最底层，是实际安装内容的只读检查。
协调与双跟踪器同步
当项目已有规范系统或跟踪器时，harness-setup 让生成的编排器与其协调：用上下文提示激活规范工作流，并在干净交接后恢复；在入口从跟踪器拉取就绪工作，在集成时写回状态。每阶段每关注点只有一个负责人，不重复产物。检测签名、协调协议和各系统协调映射共享在 shared/ 目录下。当项目同时运行仓库原生跟踪器和面向人的跟踪器（Jira、Linear、GitHub Issues）时，harness-setup 还可生成双跟踪器同步：项目本地 tracker-sync 技能和智能体，将 SaaS 跟踪器保持为仓库原生事实源的投影——持续单向推送、一次性摄入人工创建的问题、远程状态变更视为建议而非覆盖。同步状态位于仓库根目录的 .tracker-sync/；定时无头运行仅读取和报告。
执行模式与反馈循环
harness-setup 默认使用子智能体。当成员需要在任务中途对话且启用了实验性团队工具（CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1）时，使用智能体团队，并始终保留子智能体回退。每次运行都是改进工具的机会：harness-feedback 将运行转化为结构化、隐私安全的反馈，并作为 GitHub issue 提交到上游仓库。反馈格式定义在 shared/feedback-format.md，包含八个必填部分（摘要、类型、做了什么、所做选择、预期结果、实际发生/摩擦、改进建议、环境）及可选上下文。默认进行脱敏，提交前显示确切内容并需明确同意，不会静默提交。GitHub Actions 检查（feedback-check.yml）验证反馈 issue 是否包含必填部分，缺失时自动评论清单并标记 needs-info。tests/validate-feedback.sh 保持格式文档、issue 模板和 CI 检查同步。
技能与命令
可直接调用技能（/agentic-harness:harness-setup），或让 Claude 从上下文触发——这是工具链技能预期的运行方式，因为 Claude Code 已将命令合并到技能中。插件附带的一个刻意命令是 /feedback，作为 kaizen 反馈循环的可发现入口，它只是运行 harness-feedback 技能（命名为 /feedback 而非 /harness-feedback，以避免与同名技能冲突）。
安装与验证
任何更改后，运行结构验证套件（需要 jq）。在发布或提交到市场前，还需运行与评审流水线相同的检查。
适用场景与限制
适用于希望将 Claude Code 深度集成到现有代码仓库、建立可维护智能体工作流的软件项目，尤其适合已有或需要规范驱动系统、问题跟踪器的团队。限制包括：插件不执行领域工作；不自己撰写规范或问题；安装和配置委托给第三方工具；反馈提交需明确同意；部分功能依赖实验性团队工具和外部 CLI（如 gh）。项目采用 MIT 许可证，详见 LICENSE。
