Status: current Updated: 2026-03-26 Owner: engineering Purpose: Introduce this open-source starter repository and explain how it turns harness engineering principles into a practical project template.
一个面向 AI 编码工作流的 agent-native 起始模板。
这个项目把 Harness Engineering 的核心理念做成了一个最小、可运行的开源样板。它把仓库本身视为 AI agent 的工作环境：代码、文档、计划、约束、验证与反馈回路都放在版本化的项目资产里，而不是散落在聊天记录或隐性共识中。
当 AI 只负责补一个小函数时，提示词质量很重要。
当 AI 开始参与真实的软件交付时，另一件事会变得更重要：模型周围的工作环境。
这个模板围绕以下思路构建：
AGENTS.md应该是一张地图，而不是一个巨大的提示词 blob- 仓库应该成为 system of record
- 架构规则应该是可执行约束，而不是只存在于文档里
- tests、eval、health checks 和 metrics 应该组成反馈回路
- 漂移应该被持续发现和清理，而不是等到系统失控后再收拾
- 一个短小的
AGENTS.md，为 agents 指路 - 一个结构化的
docs/文档系统，用于沉淀设计、产品规格、计划、参考资料、可靠性、安全与质量规则 - 一个位于
src/的小型分层示例应用，展示显式 provider 注入和清晰领域边界 - 一组位于
scripts/的 guardrail 脚本，用于架构检查、文档检查、文档整理、eval 和质量评分 - 一个位于
.github/workflows/ci.yml的 CI 工作流，让远端执行与本地一致的 harness
.
├── AGENTS.md
├── ARCHITECTURE.md
├── docs/
│ ├── design-docs/
│ ├── exec-plans/
│ ├── generated/
│ ├── product-specs/
│ └── references/
├── scripts/
├── src/
├── tests/
└── .github/workflows/ci.yml
环境要求：
- Node.js 24+
- npm 11+
安装并验证：
npm install
npm run verify运行示例应用：
npm start然后访问：
http://localhost:3000/http://localhost:3000/healthhttp://localhost:3000/api/metrics
npm run verify # 完整验证仓库
npm run test # Node 测试
npm run eval # 可观察的验收检查
npm run lint:arch # 架构护栏检查
npm run lint:docs # 文档护栏检查
npm run docs:garden # 扫描陈旧文档
npm run quality:score # 生成质量快照这个模板把几条会显著提升 AI 编码可靠性的原则编码进仓库：
- 入口要小而稳定。
- 持久知识要进入版本化仓库文件。
- 边界要通过代码来强制，而不只靠文字说明。
- 验证要针对可观察结果，而不是实现自述。
- 清理和评分要成为系统的稳态能力。
示例应用使用严格的分层领域模型：
types -> config -> repo -> service -> runtime -> ui
持久化、时钟、遥测等基础设施能力通过 app wiring 层中的 providers 注入。
这个示例故意保持简单。重点不是 demo 功能本身，而是展示一种让 AI agents 能更安全地导航、验证和修改的代码库结构。
复制这个仓库，然后保留 harness 结构，替换其中的示例业务：
- 保持
AGENTS.md简短 - 将
docs/演进为你的 system of record - 增加或收紧架构护栏
- 围绕用户可见行为扩展 tests 与 evals
- 保持质量治理和漂移清理自动化