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 状态

状态语义契约（唯一真相源）：

• 机器状态的唯一真相源是事件账本（.claude/events/*.jsonl、.claude/worktrees/*/events/*.jsonl）。会话启动只渲染 buildProgressProjection() 的投影结果，不解析任何手写文件来推导状态。
• Current phase 只有一个语义：当前活跃 REQ 所处的阶段。无活跃 REQ 即 idle；"被阻塞"由搁置列表（suspendedReqs）表达，不复用 phase。
• Last updated 只由工作事件更新。session_started / session_ended 只表示会话开关，不改变它——打开会话不等于有进展。
• "最近事件"是流水窗口（最近 8 条 / 共 N 条），只说明最近发生了什么，不等于当前状态。
• .claude/progress.txt 不参与状态判定：CLI 会在 create/start/block/complete 时改写其头部字段，其余内容是人的笔记。会话启动把该文件原文照登（含其 Current phase: 等行），仅供人阅读，不作为机器状态。

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 或使用豁免机制