Harness Template

一个面向 AI 协作开发 的工程底座模板：把治理框架（三大基石 + 机械守卫 + AI 优先文档层） 和最小应用骨架（Python FastAPI 后端 + Vite React 前端）打包成可直接开发个人应用的起点。

提取自 ai-workbench 的 harness 工程实践。

包含什么

| 部件 | 说明 | |---|---| | 三大基石 | Superpowers（用户级技能）/ OpenSpec（变更管理）/ Harness（工作环境） | | 三平台镜像 | harness/skills/ 单源 → .claude/ .codex/ .codebuddy/（make sync-skills；镜像是生成物不入库，make init / CI 自动渲染） | | 机械守卫 | make harness-check：文档分层、命名纪律、skill 评估、镜像漂移、棘轮等 | | AI 文档层 | .ai/INDEX.yaml 四层结构 + facts / maps / playbooks | | CodeGraph | 本地代码索引 + 各平台 Stop hook 自动同步（可选件） | | 应用骨架 | apps/backend（FastAPI, :8000）+ apps/frontend（Vite React, :5173） | | 多模块规范 | make new-module NAME=<slug> 脚手架 + AGENT.md 约定 |

快速开始（渐进式初始化）

初始化是幂等且可分步的——任何一步都可以稍后补做，make doctor 永远告诉你还缺什么：

make init          # bootstrap(工具链+.env) + setup(uv sync / npm install);可后台运行
make doctor        # 环境与 harness 就绪体检;解决 error 级发现
make dev           # 启动 backend + frontend(带就绪门)
make verify-fast   # 改代码前确认守卫绿灯

AI agent 接入：会话从 AGENTS.md 和 .ai/INDEX.yaml 开始（Claude Code 自动经由 CLAUDE.md 导入）。

开发一个新应用模块

本仓库按「个人工具大仓」组织：每个工具独立放在 apps/<slug>/，类型不限 （脚本 / CLI / 常驻服务 / 浏览器插件 / 桌面应用 / 库）。应用清单见 APPS.md（生成物，make apps-registry 刷新）。

make new-module NAME=my-tool TYPE=script   # 类型: script|cli|service|browser-extension|desktop-app|library|other

脚手架会生成强制四件套，缺一不可（harness-check + pre-commit 机械强制）：

| 文件 | 内容 | |---|---| | APP.yaml | 机器清单：摘要 / 类型 / 状态 / 启动・关闭・测试命令 | | README.md | 功能说明 · 实现方案 · 使用方法（三段标题强制） | | CHANGELOG.md | 变更记录（## YYYY-MM-DD 条目；改代码必须同步落一条，CI 强制） | | AGENT.md | AI 入口：目的 / 命令 / 禁止项 |

service 类应用再按 .ai/playbooks/add-new-module.md 注册进 architecture.yaml 并接入验证。

适用边界（这个模板不适合什么）

这套底座带约 40 项机械守卫和分层文档约定，维护它们本身有成本。适合：会被 多个 AI agent 长期协作开发、模块会增长、希望规则机械化而非口头约定的项目。 不适合：一次性脚本、单文件小工具、纯实验性 notebook 项目——给这类项目 背上完整守卫是负资产，直接建普通仓库即可。介于两者之间时，可以先删掉 harness/skills/ 里用不到的技能和 docs/design/ 框架文档，守卫会跟着收缩。

模板维护说明

• .claude/.codex/.codebuddy 下的技能镜像是生成物（不入库）；克隆后由 make init 渲染，改技能只改 harness/skills/ 再 make sync-skills。
• 守卫的文本锚点契约集中在 infra/harness-expectations.tsv；改受守卫保护的 文档措辞时，同步改这一个文件即可。
• skill 评估基线（evals/baseline.json）处于 awaiting-first-run（make doctor 会以 skill-eval-baselines 警告提示），配好 ANTHROPIC_API_KEY 并用 skill-creator 的 run_eval.py 跑出首轮分数后提升为真实基线。