harness-lab: Instructions file for Claude Code

AGENTS.md

Harness Lab 是一个 研发治理层模板，不是业务运行时框架。

它的目标是让任何接手该仓库的人或 agent，都能按一致的入口、状态和交付物推进工作，而不是依赖口头上下文。

项目定位

本仓库固定的是治理协议，不固定的是业务实现。

固定内容：

• REQ 生命周期
• 设计、评审、QA、发布的交付物
• 索引优先的上下文加载顺序
• 进度交接和经验沉淀机制
• 会话启动协议和实施前检查点
• SessionStart hook 强制机制

由目标项目自己决定的内容：

• 技术栈
• 目录结构
• 架构分层
• 测试、构建、发布命令
• 领域规则和安全边界

已知限制

单用户设计：本框架面向个人开发者，不具备以下能力：

• 多租户/权限系统
• 并发控制（多人同时操作会导致数据丢失）
• 认证机制
• 审计日志

如需团队协作场景，请考虑使用 Linear、Jira 等成熟的项目管理工具。

目录导航

.
├── AGENTS.md
├── CLAUDE.md
├── context/
│   ├── business/
│   ├── tech/
│   ├── experience/
│   ├── invariants/
│   └── references/
├── docs/
│   ├── plans/
│   └── specs/
├── requirements/
│   ├── INDEX.md
│   ├── REQ_TEMPLATE.md
│   ├── in-progress/
│   ├── completed/
│   └── reports/
├── scripts/
│   ├── session-start.js      # 会话启动脚本
│   ├── req-check.js          # PreToolUse REQ 检查
│   └── req-cli.mjs           # REQ 生命周期 CLI
├── skills/
│   ├── README.md
│   ├── plan/
│   ├── review/
│   ├── qa/
│   └── ship/
└── .claude/
    ├── progress.txt
    └── settings.example.json  # hook 配置示例

强制机制

1. SessionStart Hook

为确保治理协议被执行，建议配置 SessionStart hook：

1. 复制 .claude/settings.example.json 到 .claude/settings.local.json
2. 确保 scripts/session-start.js 可执行（Windows 下无需 chmod）
3. 新会话开始时会自动显示当前 REQ 状态

2. PreToolUse Hook

在 Write/Edit/NotebookEdit 操作与 Bash 写命令前强制检查 REQ 状态与写入范围：

触发条件：Write / Edit / NotebookEdit / Bash 写命令（纯读如 ls/grep/cat 放行）
检查内容：
  1. 当前是否有活跃 REQ
  2. REQ 是否有实际内容（非模板状态）
  3. REQ 状态是否为 draft
  4. 写入文件是否超出当前 REQ 的 Scope Control / 只读边界
输出：如无活跃 REQ、REQ 为模板状态或写入越界，输出阻断信息并拒绝操作
行为：硬阻断，必须先创建并填写 REQ 或使用豁免机制

不可强制边界（上游平台限制，npm run harness:doctor 会提示）：subagent 工具调用不触发 PreToolUse（claude-code #21460 / #34692）、claude -p 非交互不触发（#40506）、perl -e / python -c 等解释器写（理论不可封）。剩余缺口靠 OS 级兜底（文件权限、容器化、CI 侧校验），详见 README「已知限制」。

补充说明：

• req:create 只负责创建骨架，不代表 REQ 已可实施
• 只有补齐真实背景、目标、验收标准后，REQ 才能通过 hook 与 req:start

豁免机制：

# 临时豁免（紧急修复、小改动）
touch .claude/.req-exempt

# 完成后删除
rm .claude/.req-exempt