Harness Setup — 项目约束系统搭建

为项目生成完整的 Harness Engineering 基础设施。

核心原理

Harness Engineering 的本质不是"加更多 linter"，而是建立闭环：

Guide（前馈）                     Sensor（反馈）
AGENTS.md 写规则        ←配对→     检查脚本验证规则
"依赖方向单向"                    check-layer-deps.sh
"单文件 ≤ 500 行"                文件大小检查
"API 入参必须校验"               Pydantic + 结构测试

没有 Guide 的 Sensor 是无主规则——Agent 不知道为什么有这条规则，自我纠正效率低。 没有 Sensor 的 Guide 是空文——Agent 看了规则但违反了也没人知道。

每条 Lint 规则必须能追溯到 AGENTS.md 或 docs/ 中的设计意图。追溯不到的，要么补文档，要么删规则。

工作流程

Step 1: 项目探测

自动检测项目信息，尽量少问用户：

1. 项目名称：从 package.json 的 name、pyproject.toml 的 name、或目录名推断
2. 技术栈：检测 requirements.txt/pyproject.toml → Python；package.json/tsconfig.json → TypeScript；两者都有 → both
3. 目录结构：检测 backend/、app/、src/ → 后端目录；frontend/、web/、client/ → 前端目录
4. 已有基础设施：检查是否已存在 .claude/、docs/、scripts/，避免覆盖

如果探测结果有歧义，用 AskUserQuestion 确认：

• 项目名称（默认：目录名）
• 技术栈（python / ts / both，默认：自动检测）
• 后端目录名（默认：backend 或 app）
• 前端目录名（默认：frontend 或 web）

Step 2: 运行初始化脚本

python3 <skill-dir>/scripts/init_harness.py \
  --project-dir <目标项目路径> \
  --project-name <项目名> \
  --tech-stack <python|ts|both> \
  --backend-dir <后端目录名> \
  --frontend-dir <前段目录名>

脚本会生成以下基础设施：

信息层（Guide/前馈）

• .claude/CLAUDE.md — 地图模式入口（~80 行），含快速导航表 + 硬性规则 + 可测试性分级
• .claude/rules/ — 按文件类型自动注入的编码规范（python-style / frontend-style / security / docs-sync）
• docs/ — 结构化知识库（architecture / conventions / design / plans / reference）

约束层（Sensor/反馈）

• scripts/check-layer-deps.sh — 架构依赖方向检查（错误信息三要素格式）
• scripts/check-guide-sensor-pairing.sh — Guide+Sensor 配对验证（确保每条规则有对应检查）
• scripts/check-lint-expiry.sh — Lint 规则过期追踪（90 天未触发的规则标记审查）
• scripts/check-doc-freshness.sh — 文档新鲜度检查
• .claude/hooks/ — 安全拦截 + 自动格式化 + 文档同步提醒

自动化层

• scripts/harness-check.sh — 全量检查入口（一键跑完所有验证）
• scripts/agent-verify.sh — Git Worktree 隔离验证
• .github/workflows/harness-checks.yml — CI 管线（7 道门）
• .claude/agents/ — 4 个分工代理（architect / coder / reviewer / cleanup）

模板变量自动替换（项目名、目录名、日期、技术栈）。.sh 文件自动赋予执行权限。已存在的文件不覆盖（打印跳过提示）。

Step 3: 生成汇总报告

脚本执行完毕后，向用户展示：

✅ Harness Engineering 基础设施已初始化

文件清单：
  新增 N 个文件
  跳过 N 个文件（已存在）

生成内容：
  信息层（Guide）  .claude/CLAUDE.md + rules/ + docs/
  约束层（Sensor）  scripts/ 四个检查脚本
  自动化层          CI 管线 + 4 个 Agent + Worktree 验证

下一步：
  1. 审阅 CLAUDE.md 中的硬性规则和可测试性分级，按需调整
  2. 审阅 docs/architecture/boundaries.md 中的依赖方向
  3. 运行 bash scripts/harness-check.sh 验证
  4. 运行 bash scripts/check-guide-sensor-pairing.sh 检查配对完整性
  5. 提交代码，CI 管线自动生效

长期维护：
  - 每次模型大版本升级后做一次 harness 压测
  - 月度 "Harness 园艺日"：修剪过时约束、补充新传感器
  - 运行 bash scripts/check-lint-expiry.sh 查看过期规则

注意事项

• 不覆盖已有文件：已有 .claude/CLAUDE.md 时跳过并提示手动合并
• 技术栈适配：--tech-stack python 时不生成前端相关规则；--tech-stack ts 时不生成 Python 规则
• 目录名灵活：后端目录可以是 app、backend、src，脚本按实际名称生成约束
• 错误信息三要素：所有检查脚本的报错都包含 ❌ 问题 + ✅ FIX + 📖 文档链接，让 Agent 能自我纠正