Harness 贡献指南全解：SLA 承诺、开发环境搭建与 Conventional Commits 提交规范

Harness 贡献指南全解SLA 承诺、开发环境搭建与 Conventional Commits 提交规范【免费下载链接】harnessA meta-skill that designs domain-specific agent teams, defines specialized agents, and generates the skills they use.项目地址: https://gitcode.com/GitHub_Trending/harness/harness本文以仓库 CONTRIBUTING.md 为骨架结合 README.md、docs/experimental-dependency.md、docs/quickstart.md、CHANGELOG.md 以及.github/下的真实 Issue / PR 模板完整讲解Harness开源项目的协作规范维护者向社区承诺的响应 SLA、不同类型的贡献入口、本地开发环境搭建、PR 分支与提交信息约定、Conventional Commits 到 SemVer 的映射以及行为准则与维护者名单。读完你可以直接按规范提交一个高质量 PR也能理解这个为 Claude Code 生成 Agent 团队与技能的 meta-skill 工厂项目是如何组织协作的。一、项目定位你在为怎样的项目做贡献Harness是 Claude Code 生态中位于L3 Meta-Factory / Team-Architecture Factory层的插件输入一句领域描述如build a harness for a fintech risk-assessment team输出一套专用 Agent 定义.claude/agents/与配套技能.claude/skills/。其内部调用 Claude Code 的Agent Teams APITeamCreate/SendMessage/TaskCreate并内置 6 种团队架构模式Pipeline、Fan-out/Fan-in、Expert Pool、Producer-Reviewer、Supervisor、Hierarchical Delegation。对贡献者而言这意味着你的改动很可能落在skill 定义skills/harness/SKILL.md 及其 references、agent 模板、插件清单、文档README / docs/或CI 工具链上。CONTRIBUTING.md 开篇即声明其覆盖范围响应 SLA、贡献方式、开发环境、PR 约定、提交信息规则、行为准则与维护者名单——本文逐一展开。二、响应 SLA维护者的公开承诺可据此催办Harness 由小规模维护团队运营因此 SLA 目标定得保守且可达成。原文表格完整如下这是社区协作的契约基线表面目标说明PR — 首次响应 72 小时按工作日计。首次响应最低要求 至少一个 label 一条确认收到 PR 的评论Issue 分类与打标 48 小时每个新 Issue 在 48h 内移除needs-triage并打上类型 labelbug/enhancement/question/discussionBug 修复P0 / P1 14 天P0 数据丢失 / 安全 / 安装破坏P1 常见路径被破坏。P2/P3 进入路线图跟踪无硬性 SLA安全报告 7 天7 天内给出初步确认修复目标 30 天。请走下方Security私有渠道发布节奏每 2 周双周打 tag除非无可发布内容P0 修复可插入计划外 patch 发布需要特别指出这些是社区承诺而非付费 SLA。docs/experimental-dependency.md 中的Monitoring Commitment进一步将其落成可观测机制——例如Anthropic 发布 Agent Teams / Managed Agents 变更后本文档须在 72 小时内更新、夜间 CI 检测到兼容性破坏后 24 小时内开 hotfix 分支违规可打sla-breachlabel 提交 Issue。文档明确写道如果维护者错过了 SLA请在 Issue/PR 中直接 ping——这不是失礼而是约定的反馈回路that is not rude, it is the agreed feedback loop。三、如何贡献按类型选择入口不同贡献走不同入口原文档给出了 5 类路径实际对应的模板文件已存在于仓库.github/ISSUE_TEMPLATE/目录。3.1 Bug 报告使用Bug report表单.github/ISSUE_TEMPLATE/bug_report.yml提交 Issue必填字段Claude Code 版本claude --version输出、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS标志状态开启 / 未开启 / 不清楚、复现步骤、期望行为 vs 实际行为、操作系统macOS / Linux / Windows WSL / Windows 原生 / 其他理想粒度小于 30 行的最小复现若复现需要完整项目请链接一个公开 fork。仓库中该模板与 CONTRIBUTING.md 完全对应表单头部嵌入了48h 打标、72h 实质响应的 SLA 提示且把flag 状态设计为强制下拉选项——这是因为 Harness 的团队执行模式依赖实验性标志见第四节flag 未设置本身就是最常见的 bug 根因之一。3.2 功能请求使用Feature request表单.github/ISSUE_TEMPLATE/feature_request.yml需要一段简短这个问题解决什么的说明若有具体方案请直接整理成PR-ready 形态说明它扩展 / 替换了 6 种团队架构模式中的哪一个。这提示了该项目的核心抽象——一切功能演进都围绕团队架构模式展开。3.3 提问使用Question表单提交 Issue若问题开放性强改在仓库的Discussions板块发起讨论原文档给出了 Discussions 链接社区讨论遵循先讨论、后成 Issue的节奏。3.4 讨论RFC 级别的想法优先使用 GitHub Discussions仅在方向取得大致共识后升级为 Issue。这也是项目小 PR 快速合并文化的上游改动超过 400 行 diff 的 PR 大概率应该先是一场 Discussion。3.5 Pull Request先阅读下文PR 指南小 PR 合并更快。3.6 安全报告特殊通道不要对可能被滥用的安全问题开公开 Issue通过私有渠道提交邮件robin.hwangkakaocorp.com主题前缀[harness-security]承诺 7 天内初步确认见 SLA 表。同样地行为准则违规举报使用主题前缀[harness-coc]。四、开发环境搭建4.1 前置条件依赖版本要求用途Claude Codev2.x需 Agent Teams API插件运行时的宿主Node.js 18CI 用本地工具链markdownlint 等Git任意现代版本版本控制当前仓库未包含package.json/ Node 项目骨架Node.js 仅用于运行npx markdownlint这类按需拉取的 CLI 工具这是本地工具链用于 CI的典型轻量做法。4.2 实验性环境标志关键前提Harness 目前依赖 Claude Code 的实验性 Agent Teams 功能必须在启动claude的 shell 中设置export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS1建议写入 shell profile~/.zshrc/~/.bashrc以跨会话持久化。该依赖的完整机理记录在 docs/experimental-dependency.md三个被标志门控的原语TeamCreate实例化多 Agent 团队、SendMessage团队成员间路由消息、TaskCreate在团队内派生长任务全部需要该标志仅单 Agent 派发的Agent工具是 GA 路径、不依赖标志若未设置该变量生成的团队会静默回退为单 Agent 执行从而悄然破坏 Pipeline / Fan-out-Fan-in / Supervisor / Hierarchical Delegation 模式——这正是 Bug 模板中强制询问 flag 状态的原因文档为标志的三种未来A移除标志转 GABManaged Agents 并行 GACAPI 破坏性变更各预演了 T24h / 48h / 72h 行动清单并承诺 Anthropic 变更后 72h 内更新本文档。从 CHANGELOG.md 看v1.2.0 起该标志的依赖管理已进入正式治理README 与 plugin 清单版本统一、docs/文档空间开辟。4.3 本地插件链接不发布即可自测从你的 checkout 目录执行# 从你的检出目录 claude plugin link ./harness # 验证 claude plugin list | grep harness结束自测后解除链接claude plugin unlink harness这与 docs/quickstart.md 的 marketplace 安装路径claude plugin marketplace add revfactory/harness→claude plugin install harnessharness互为补充链接模式用于开发验证marketplace 模式用于最终用户安装。4.4 运行 meta-skillclaude build a harness for a fintech risk-assessment team脚手架生成的 Agent 与技能会落到目标项目的.claude/agents/和.claude/skills/下。这也是贡献者验证自己改动最直接的方式——改完 skills/harness/SKILL.md 后跑一遍完整 6 阶段工作流Domain Analysis → Team Architecture Design → Agent Definition → Skill Generation → Integration Orchestration → Validation Testing。4.5 测试与 Lint# Markdown lint覆盖全部 md npx markdownlint **/*.md # YAML lintIssue 模板与 workflows npx yaml-lint .github/ # 技能元数据校验若存在该脚本 python scripts/validate_skills.py两点细节值得注意CI 会在每个 PR 上运行这些检查但本地执行是鼓励而非强制——仓库不会因 CI 抓到的小问题卡住合并会在合并时顺手修掉we wont block on CI-caught issues that are trivial to fix on merge第三行标注if present当前仓库中并不存在scripts/validate_skills.py这是一条条件性命令切勿在无该脚本的环境中直接依赖它。目前仓库也没有.github/workflows/下的实际 workflow 文件CI 配置仍处于 roadmap 阶段内部审计文档将添加基础 GitHub Actions CI列为高优先级建议。五、Pull Request 指南5.1 分支命名type/short-description前缀用途示例feat/新的用户可见能力feat/expert-pool-variance-modefix/Bug 修复fix/agent-teams-flag-detectiondocs/仅文档改动docs/quickstart-gemini-sectionrefactor/内部结构调整无行为变化refactor/skill-loader-splitchore/构建、依赖、日常维护chore/upgrade-markdownlinttest/仅测试test/fan-out-fan-in-e2e5.2 提交信息语言韩语与英语均被接受——用你表达最精确的语言写若改动会进入 CHANGELOG 或 release notes请在 PR 描述中补充英文标题方便下游读者跟进。5.3 PR 模板每个 PR 正文由 .github/PULL_REQUEST_TEMPLATE.md 预填需填写五个板块与 CONTRIBUTING.md 的约定一一对应Summary改了什么、为什么2–4 句Motivation链接 Issue / RFC / 研究资料或 1 行理由Scope of change勾选改动面清单——技能 / meta-skill 逻辑、Agent 模板、插件清单.claude-plugin/plugin.json、marketplace.json、文档、CHANGELOG.md、CI、测试、其他Tests记录本地跑过的命令与结果模板直接内置npx markdownlint **/*.md勾选项CHANGELOG是否已更新CHANGELOG.mdY/N/NASemVer impactpatch / minor / major / none依据下一节映射。该模板还内嵌了约束每个用户可见变更必须落入CHANGELOG.md的 Unreleased 段——这是 CHANGELOG.md 当前结构[Unreleased]→[1.2.1]→[1.2.0]→ …得以长期维持的机制保障。5.4 评审预期需要1 名维护者的 approving reviewPR 响应目标 72h见 SLA 表被阻塞就 ping。六、提交信息约定Conventional Commits 轻量变体 → SemVer仓库遵循Conventional Commits 的轻量变体直接映射到 SemVertype(scope)!: 简短摘要 body — 可选 footer — 可选6.1 类型与 SemVer 映射表提交类型SemVer 影响示例feat!:或 footer 含BREAKING CHANGE:major如 1.x → 2.0feat!: rename primary pattern Supervisor → Orchestratorfeat:minor如 1.2 → 1.3feat: add Producer-Reviewer variance metricfix:patch如 1.2.3 → 1.2.4fix: correct flag detection on zshdocs:/chore:/refactor:/test:不触发版本提升docs: clarify Gemini roadmap要点韩语摘要完全可用例如feat: 전문가 풀 패턴에 분산 지표 추가!后缀或BREAKING CHANGE:footer是唯一规范的 major 触发机制请勿随意使用——仓库对 breaking 语义保持强约束。对照 CHANGELOG.md 的历史可以印证这套映射的实际运作v1.0.06 Phase 工作流 6 架构模式、v1.1.0Phase 0 现状审计、进化机制等新能力 minor、v1.2.0 / 1.2.1版本统一、CONTRIBUTING.md 引入、文档空间开辟 非破坏性演进其中 1.2.1 是纯修正性 patch。发布节奏方面每 2 周从main打 tag前提是 CI 通过且 CHANGELOG 已更新tag 格式为vMAJOR.MINOR.PATCH如v1.3.0。七、行为准则与维护者7.1 Code of Conduct项目遵循Contributor Covenant v1.4核心要点保持欢迎与包容假定善意禁止骚扰、人身攻击、歧视性语言批评观点而非人尽量用参考资料支撑主张维护者有权对违反上述原则的评论 / 提交 / Issue / PR 进行管理、编辑或移除并可能封禁违规者。违规举报走私有渠道邮件robin.hwangkakaocorp.com主题前缀[harness-coc]。7.2 维护者名单角色Handle负责领域首席维护者revfactory项目方向、发布、最终评审贡献者hnts03技能模板、韩语文档贡献者JunghwanNAAgent 模式、集成测试贡献者shaun0927工具链、CI、基础设施成为维护者的路径是持续贡献而非单次 PR有意向可在 Discussions 中沟通。八、许可证与贡献者义务项目采用Apache 2.0见 LICENSE提交贡献即表示同意你的贡献以仓库相同许可证授权。九、给贡献者的行动清单提交前确认CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS1在你的 shell 中生效并记录claude --version这是 Bug 模板的两个必填项分支按type/short-description命名如feat/...、fix/...提交Conventional Commits 格式注意feat!:/BREAKING CHANGE:是唯一 major 触发器PR按 .github/PULL_REQUEST_TEMPLATE.md 完整填写 Summary / Motivation / Scope / Tests / CHANGELOG / SemVer本地验证npx markdownlint **/*.md与npx yaml-lint .github/scripts/validate_skills.py仅在该脚本存在时执行预期节奏PR 首次响应 72h、Issue 打标 48h错过 SLA 可以 ping安全事项安全问题走[harness-security]私有邮件绝不公开。遵循上述约定你的改动将能以最小的沟通成本被这个小而高效的维护团队接收、评审并进入双周发布节奏。【免费下载链接】harnessA meta-skill that designs domain-specific agent teams, defines specialized agents, and generates the skills they use.项目地址: https://gitcode.com/GitHub_Trending/harness/harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考