从零搭建 Agent Harness：工程师实操指南

your-repo/
├── CLAUDE.md                    # <60 行，手写
├── .claude/
│   ├── settings.json            # Hook 定义
│   ├── hooks/
│   │   └── verify.sh            # 验证脚本
│   ├── rules/                   # 模块化规则（可选）
│   └── skills/                  # 先空着
└── docs/
    ├── architecture.md          # 依赖流向、系统边界
    └── standards.md             # 命名、日志、错误处理

# Project
[一句话描述项目]

# Architecture
Unidirectional dependency flow: Types → Config → Repo → Service → Runtime → UI
Dependencies NEVER flow backward.

# Commands
- Build: npm run build
- Test: npm run test
- Single test: npm run test -- --grep "test name"
- Lint: npm run lint
- Typecheck: npx tsc --noEmit

# Standards
- Use ES modules (import/export), not CommonJS (require)
- Structured logging (JSON format)
- All public functions have docstrings

# Gotchas
- IMPORTANT: Never import from @internal/* in client code
- Database migrations require `npm run db:generate` after schema changes

# Tools
Use CLI for GitHub operations:
- `gh pr create --title "..." --body "..."`
- `gh issue view 123`
Do NOT use MCP servers for things the CLI handles.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/verify.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

#!/bin/bash
set -euo pipefail
cd "$CLAUDE_PROJECT_DIR"

# 并行跑类型检查和 lint
ERRORS=""
npx tsc --noEmit 2>&1 | tail -20 > /tmp/tc_out || ERRORS+="$(cat /tmp/tc_out)
"
npx eslint --quiet . 2>&1 | tail -20 > /tmp/lint_out || ERRORS+="$(cat /tmp/lint_out)
"

if [ -n "$ERRORS" ]; then
  echo -e "$ERRORS" >&2
  exit 2  # exit 2 = 让 agent 修复问题
fi

# 成功 = 沉默。不打印任何东西。

chmod +x .claude/hooks/verify.sh

#!/bin/bash
# .claude/hooks/check-errors.sh
tail -100 /var/log/app/error.log \
  | jq -r '.timestamp + " " + .level + " " + .message' 2>/dev/null \
  || echo "No recent errors"

# Observability
- Recent errors: `.claude/hooks/check-errors.sh`
- Metrics summary: `.claude/hooks/check-metrics.sh`
- Only show errors, do NOT dump full logs

Git workflow: @docs/git-instructions.md
API docs: @docs/api-reference.md

.claude/rules/
├── code-style.md       # 通用，始终加载
├── testing.md          # 通用
├── security.md         # 路径限定
└── api.md              # 路径限定

---
paths: src/api/**/*.ts
---
# API Rules
- All endpoints must validate input with Zod
- Return consistent error shapes
- Use parameterized queries exclusively

---
paths:
  - src/auth/**/*
  - src/payments/**/*
---
# Security-Critical Code
- Never log sensitive data (PII, tokens, passwords)
- All auth changes require human review
- Use parameterized queries exclusively

---
paths: prisma/migrations/**/*
---
# Migration Safety
- Always include rollback instructions
- Never drop columns without two-phase migration
- Test on production data copies first

// 1. Shell 命令（最常用）
{"type": "command", "command": ".claude/hooks/verify.sh", "timeout": 30}

// 2. HTTP 端点
{"type": "http", "url": "http://localhost:8080/hooks/check", "timeout": 10}

// 3. LLM 判断（yes/no 决策）
{"type": "prompt", "prompt": "Is this change safe?", "model": "fast-model"}

// 4. Agent（有工具的 LLM）
{"type": "agent", "prompt": "Verify setup", "model": "default"}

#!/bin/bash
# .claude/hooks/block-dangerous.sh
COMMAND=$(jq -r '.tool_input.command' < /dev/stdin)

if *"$COMMAND" == rm\ -rf** || *"$COMMAND" == *--force**; then
  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Destructive command blocked"}}' 
  exit 0
fi
exit 0

#!/bin/bash
# .claude/hooks/auto-format.sh
INPUT=$(cat /dev/stdin)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path')

if *"$FILE_PATH" == *.ts* || *"$FILE_PATH" == *.tsx*; then
  npx prettier --write "$FILE_PATH" 2>/dev/null
fi
exit 0

#!/bin/bash
# .claude/hooks/notify-done.sh
osascript -e 'display notification "Claude finished" with title "Claude Code"' 2>/dev/null \
  || echo -e '\a'  # fallback: terminal bell

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npx jest *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git status)"
    ],
    "deny": [
      "Bash(curl *)",
      "Bash(wget *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(npm publish *)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous.sh",
            "timeout": 10
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/verify.sh",
            "timeout": 30
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-format.sh",
            "async": true
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/notify-done.sh"
          }
        ]
      }
    ]
  }
}

.claude/skills/
├── fix-issue/
│   └── SKILL.md
├── deploy-preview/
│   ├── SKILL.md
│   └── scripts/
│       └── validate.sh
└── api-conventions/
    └── SKILL.md

---
name: fix-issue
description: Fix a GitHub issue end-to-end
disable-model-invocation: true
---
Analyze and fix GitHub issue: $ARGUMENTS

1. `gh issue view $ARGUMENTS` to get details
2. Search codebase for relevant files
3. Implement fix
4. Write and run tests
5. Ensure lint and typecheck pass
6. Create commit with descriptive message
7. Push and create PR

---
name: pr-summary
context: fork
agent: Explore
---
## PR Context
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`

Summarize this PR...

"找到 processPayment 的定义，返回文件路径和行号"
"分析代码库中所有使用已废弃 oldAuth 的地方"
"追踪 /users 端点到数据库的数据流"

"你是前端工程师"  ← 不工作
"你是后端工程师"  ← 不工作

□ 创建 CLAUDE.md（<60 行，手写，通用规则）
□ 创建 docs/architecture.md（依赖流向图）
□ 创建 .claude/settings.json（一个验证 hook）
□ 创建 .claude/hooks/verify.sh（typecheck + lint，成功沉默）
□ chmod +x .claude/hooks/verify.sh
□ 跑一个真实任务，观察哪里失败
□ 不要加 MCP servers、skills、sub-agents

□ 添加 1-2 条针对观察到的失败模式的 lint 规则
□ 为外部工具写 wrapper CLI
□ 在 CLAUDE.md 中添加 CLI 用法示例
□ 如有上下文腐烂，创建首个 subagent 委托模式

□ 为复杂多步工作流创建 1-2 个 skills
□ 添加可观测性 hooks（结构化日志访问）
□ 为关键用户旅程构建首个验收测试
□ 审查并删除没有积极改善输出的一切
□ 将有效配置通过 git 共享给团队