6.6 为一个项目搭最小 Harness¶

阅读完本节后，你应该能在一个普通 repo 里搭出最小可用的 Agent 开发 harness，让 Codex / Claude Code 每次工作都更稳定。

Harness Engineering 听起来大，但起步可以很小。这里讲的是从普通 repo 搭起第一版 harness 的步骤；如果你只需要概念，回到 2.3 Harness Engineering；如果你需要可复制的最终模板，直接看 9.4 最小项目模板和落地步骤。

最小 harness 只需要解决 4 个问题：

Agent 应该读什么？
Agent 应该怎么做？
Agent 怎么验证？
Agent 做完后怎么留下状态？

最小目录结构¶

.
├── AGENTS.md 或 CLAUDE.md
├── docs/
│   ├── commands.md
│   └── architecture.md
└── tasks/
    └── current/
        ├── prd.md
        ├── plan.md
        └── journal.md

如果你同时使用 Codex 和 Claude Code，可以维护一份共享规则，再做工具适配：

AGENTS.md
CLAUDE.md
docs/agent-common.md

第 1 步：写 Agent 入口规则¶

AGENTS.md 或 CLAUDE.md：

# Agent Rules

## Start Here

Before editing, read:
- `docs/commands.md`
- `docs/architecture.md`
- current task under `tasks/current/` if present

## Working Rules

- Start with read-only analysis for non-trivial tasks.
- Keep changes minimal and scoped.
- Do not introduce new dependencies without confirmation.
- Do not modify `.env` or secrets.
- Do not revert unrelated user changes.
- Run relevant validation before saying done.

## Done Means

- Acceptance criteria are satisfied.
- Relevant tests or checks were run.
- If checks cannot run, explain why and provide manual verification.
- Update docs if commands, architecture, public API, or conventions changed.

第 2 步：写命令文档¶

docs/commands.md：

# Commands

## Install

`pnpm install`

## Development

`pnpm dev`

## Test

`pnpm test`

## Typecheck

`pnpm typecheck`

## Lint

`pnpm lint`

## Build

`pnpm build`

## Notes

- Use `pnpm`, not `npm`.
- If a command fails because dependencies are missing, report it instead of switching package managers.

这能阻止 Agent 乱猜命令。

第 3 步：写架构索引¶

docs/architecture.md 可以先写成下面这种结构：

# Architecture

## Purpose

[项目一句话目标]

## Main Directories

- `src/app/`: routes and pages.
- `src/components/`: UI components.
- `src/lib/`: shared logic.
- `src/server/`: server-side business logic.
- `tests/`: tests.

## Data Flow

这里放一张 Mermaid 数据流图，避免用纯文本箭头描述调用链。

示例：

flowchart LR
  A[User action] --> B[API route]
  B --> C[service]
  C --> D[database]
  D --> E[response]
  E --> F[UI state]

继续补充架构规则：

## Important Rules

- Business logic belongs in services, not route handlers.
- Shared validation schemas live in `src/lib/validation`.
- Public API changes require tests and docs updates.

架构文档不要追求完整，先让 Agent 找得到方向。

第 4 步：写当前任务 PRD¶

tasks/current/prd.md：

# Current Task

## Goal

[本次任务目标]

## User Value

[为什么要做]

## Requirements

- [ ] Requirement 1
- [ ] Requirement 2

## Out of Scope

- [ ] Not doing X
- [ ] Not changing Y

## Acceptance Criteria

- [ ] Checkable criterion 1
- [ ] Checkable criterion 2

## Risks

- Risk 1
- Risk 2

第 5 步：让 Agent 生成计划¶

tasks/current/plan.md 可以让 Agent 写。

请读取 AGENTS.md、docs/commands.md、docs/architecture.md 和 tasks/current/prd.md。
先不要修改代码。
请生成 tasks/current/plan.md，包含：
- 现状理解。
- 需要修改的文件。
- 实施步骤。
- 风险。
- 验证命令。
- 回滚或恢复策略。

计划确认后再进入实现。

第 6 步：维护 journal¶

tasks/current/journal.md：

# Journal

## YYYY-MM-DD HH:mm

### Done

- Completed X.

### Validation

- Ran `pnpm test`: passed.

### Issues

- Y failed because Z.

### Next

- Continue with A.

长任务中，journal 是恢复上下文的关键。

使用方式¶

每次新会话开头：

请按项目 harness 工作。
先读取 AGENTS.md / CLAUDE.md、docs/commands.md、docs/architecture.md 和 tasks/current/。
不要修改文件，先总结当前任务状态和下一步计划。

什么时候升级¶

痛点	升级
多任务并行混乱	每个任务独立目录
多 Agent 冲突	worktree
规则越来越多	specs 分层
重复流程太多	skills
外部信息搬运重	MCP
质量不稳定	eval / checklists / CI gates

完成标准¶

[ ] Agent 进入项目后知道先读哪里。
[ ] Agent 不再乱猜验证命令。
[ ] 每个任务都有 PRD 和验收标准。
[ ] 长任务中断后可以从 journal 恢复。
[ ] 文档同步被纳入 Done Definition。