用途
harness-init 是一个面向 Agent 协作开发的极简仓库模板,核心理念是“人定方向,Agent 执行”,规则、知识和变更记录全部版本化。模板本身不附带脚本和 Makefile,所有文件由 Agent 按指引创建。
两种模式
初始化模式:当用户明确提到 harness-init、harness 模板,或要求按该模板创建项目时触发,从零创建 Agent-first 项目骨架。若用户只是普通地要求“创建项目”“初始化仓库”“搭骨架”,则不应触发,按普通项目处理。
协作模式:当当前仓库已经是 harness-init 结构时使用,遵循既有约定开展协作。
初始化模式流程
- 确认基本信息:向用户确认项目名称(必须)、项目类型(必须,如 Web/API、前后端分离、桌面端、CLI/工具、库/SDK)、是否需要前端界面或其他专项约束。
- 创建目录结构:生成 AGENTS.md、CLAUDE.md、README.md、CODEOWNERS、LICENSE、.editorconfig、.gitattributes、.gitignore、.markdownlint.json,以及 docs/ 下的 ARCHITECTURE.md、HISTORY_GUIDE.md、PLANS_GUIDE.md、REPO_COLLAB_GUIDE.md、exec-plans/(含 README、tech-debt-tracker、active、completed、templates/execution-plan.md)和 histories/template.md。默认只保留 4 份“灵魂”文档加 ARCHITECTURE,其他专题文档等真实项目落地后按需新增。
- 按项目类型实例化关键文档:不能只做模板名替换,README.md 需写真实项目简介、启动方式、目录结构;AGENTS.md 保留导航角色并明确本项目最关键的 plan/history 约束;docs/ARCHITECTURE.md 需写真实模块边界、运行拓扑、数据流。按项目类型可选新增专题文档:Web/API/后端服务对应 RELIABILITY、SECURITY、CICD;前后端分离对应 FRONTEND、RELIABILITY、CICD;桌面端/客户端对应 DESIGN、RELIABILITY、SECURITY;CLI/SDK/库对应 DESIGN、CICD。项目类型不明确时应先补齐类型,不应假装初始化完成。
- 生成文件内容:读取 references/init-files.md 获取各文件完整内容,替换 {{PROJECT}} 占位符,文档使用中文,换行符 LF,.editorconfig 采用 UTF-8、2 空格缩进。按项目类型新增的可选专题文档需基于真实项目事实新写。
- 手工核对骨架:确认 4 份灵魂文档齐全、ARCHITECTURE.md 已实例化、exec-plans 下 3 个子目录就位、histories/template.md 存在、基础设施文件齐全。
- 提示用户下一步:确认 README、AGENTS、ARCHITECTURE 三份已实例化,替换 CODEOWNERS 中的占位团队名,按需创建 apps/、packages/、infra/,真实业务接入后再补专题文档。
协作模式约定
每轮任务开始必读:依次阅读 AGENTS.md(导航入口,只做路由)、docs/REPO_COLLAB_GUIDE.md(协作约定)、docs/ARCHITECTURE.md(架构总览)。改完代码前必读 docs/HISTORY_GUIDE.md。复杂多步任务参阅 docs/PLANS_GUIDE.md,专题文档视 docs/ 下当时存在的文件而定。
核心工作规则:知识落仓库,重要信息不能只留在聊天记录中;行为变化时代码、文档、history 在同一轮更新;优先选择简单、清晰、可观测的方案;Agent 反复失败时优先修环境、修指引、修规范;AGENTS.md 只做路由,知识来源在 docs/;不依赖脚本。
复杂任务创建执行计划:当任务跨多个 commit 或工作轮次、涉及架构/协议/数据迁移等高风险变更、需要分阶段验证或回滚策略、或多人多 Agent 协作时,复制 templates/execution-plan.md,命名为 docs/exec-plans/active/YYYY-MM-DD-<slug>.md,完成后移至 completed/。
记录变更历史:每次有实质性仓库变更时,复制 docs/histories/template.md,按需创建 docs/histories/YYYY-MM/ 目录,命名为 YYYYMMDD-HHmm-<task-slug>.md,内容包括脱敏后的用户请求、主要代码/文档变更、设计意图、关键受影响文件。纯问答或研究任务(仓库无实际变化)不需要记录。
提交前确认:文档已同步更新、变更历史已记录、示例和说明文档与当前实现一致。
参考文件
references/init-files.md 提供初始化模式所需的全部文件内容;references/conventions.md 提供协作模式的详细约定、模板和工作流程。
适用场景与限制
适用于希望让 Agent 参与开发并保持规则、知识、变更记录可追溯的项目团队。注意仅在用户明确要求使用该模板时触发初始化模式;项目类型不明确时不应急于完成初始化;模板不含脚本和 Makefile,具体可选专题文档需基于真实项目事实编写。