修 Bug 的真正目的：让 AI 下次能自己修

Agent = Model + Harness

┌─────────────────────────────────────────────────┐
│                  Harness 全景                    │
├──────────────┬──────────────┬───────────────────┤
│  Guides      │  Sensors     │  Quality Gates    │
│  (前馈控制)   │  (反馈回路)   │  (强制门禁)        │
├──────────────┼──────────────┼───────────────────┤
│ CLAUDE.md    │ TypeScript   │ CI/CD Pipeline    │
│ AGENTS.md    │ ESLint       │ Git Hooks         │
│ .claude/     │ Pytest       │ PR Review Bot     │
│   rules/     │ Playwright   │ Mutation Test     │
│ Skills       │ Structured   │ Dependency        │
│              │ Error Msgs   │ Staleness Gate    │
│ Architecture │              │                   │
│ Docs         │              │                   │
└──────────────┴──────────────┴───────────────────┘

# 不要只说 "fix the bug"
$ claude "users report that login fails after session timeout.
          check the auth flow in src/auth/,
          especially token refresh.
          write a FAILING test that reproduces the issue,
          then fix it"

🔴 Red:    写一个失败测试，确认 Bug 可复现
🟢 Green:  写最小修复代码，让测试通过
🔵 Refactor: 重构，保持测试通过

Error: Something went wrong

{
  "error_code": "AUTH_TOKEN_EXPIRED",
  "context": {
    "user_id": "u_123",
    "token_expired_at": "2026-05-25T10:00:00Z",
    "refresh_endpoint": "/api/auth/refresh"
  },
  "suggested_action": "Call refresh endpoint with valid refresh_token"
}

# Error Handling
- All API errors use structured format: { error_code, context, suggested_action }
- Error codes follow pattern: MODULE_ACTION_REASON (e.g., AUTH_TOKEN_EXPIRED)
- When fixing errors, always add structured context fields
- Never return raw stack traces to clients

tests/
├── fixtures/
│   ├── expired_session.json      # 过期 session 的完整状态
│   ├── malformed_webhook.json    # 畸形 webhook payload
│   └── race_condition_setup.py   # 竞态条件的初始化脚本

# tests/test_session_refresh.py
import json
from pathlib import Path

FIXTURES = Path(__file__).parent / "fixtures"

def test_session_timeout_recovery():
    """Regression: session timeout caused login failure (Issue #342)"""
    expired_state = json.loads(
        (FIXTURES / "expired_session.json").read_text()
    )
    response = client.post("/api/auth/refresh", json=expired_state)
    assert response.status_code == 200
    assert "new_token" in response.json()

$ claude "I'm seeing a parsing error with webhook payload X.
          Save this payload as tests/fixtures/bad_webhook.json,
          write a test that fails with it, then fix the parser"

#!/bin/bash
# scripts/diagnose_auth.sh - 认证问题诊断脚本
# 用法: ./scripts/diagnose_auth.sh <user_id>

USER_ID=$1

echo "=== Step 1: Check token status ==="
redis-cli get "session:${USER_ID}:token" | jq .

echo "=== Step 2: Check recent auth logs ==="
kubectl logs -l app=auth-service --since=1h | grep "${USER_ID}" | tail -20

echo "=== Step 3: Check rate limiting ==="
redis-cli get "ratelimit:${USER_ID}:auth"

echo "=== Step 4: Validate config ==="
kubectl get configmap auth-config -o yaml | grep -A5 "session_ttl"

# Debugging
- Auth issues: run `./scripts/diagnose_auth.sh <user_id>` first
- Performance issues: run `./scripts/profile_endpoint.sh <path>`
- Always run diagnostic scripts BEFORE making code changes

~/projects/CLAUDE.md              ← Global: 通用标准 (TDD, 安全, 命名)
~/projects/my-app/CLAUDE.md       ← Project: 架构, 命令, 坑, 文档地图
.claude/rules/                    ← Path-Scoped: 按文件路径自动加载

<!-- .claude/rules/auth.md -->
---
globs: ["src/auth/**", "src/middleware/session*"]
---
# Auth Module Rules
- Token validation MUST check expiry BEFORE signature
- Session refresh MUST invalidate old token atomically
- All auth failures MUST return structured error with AUTH_ prefix
- Rate limiting: 5 attempts per minute per user_id
- When in doubt, check tests/fixtures/expired_session.json

#!/bin/sh
# .husky/pre-commit

# 1. Lint (自动修复)
npx lint-staged

# 2. Secret scan (防密钥泄露)
npx gitleaks protect --staged

# 3. File size check (≤300 行)
for file in $(git diff --cached --name-only --diff-filter=ACM); do
  lines=$(wc -l < "$file" 2>/dev/null || echo 0)
  if [ "$lines" -gt 300 ]; then
    echo "❌ $file exceeds 300 lines ($lines). Split it."
    exit 1
  fi
done

# 4. Test colocation (src/ 下的文件必须有对应测试)
for file in $(git diff --cached --name-only --diff-filter=ACM | grep "^src/"); do
  test_file=$(echo "$file" | sed 's/\.ts$/.test.ts/')
  if [ ! -f "$test_file" ]; then
    echo "❌ No test found for $file. Create $test_file"
    exit 1
  fi
done

FAIL tests/test_auth.py

{
  "status": "failed",
  "suite": "auth",
  "test": "test_session_timeout_recovery",
  "error": "AssertionError: expected 200 but got 401",
  "location": "tests/test_auth.py:42",
  "context": {
    "expected_status": 200,
    "actual_status": 401,
    "response_body": "{\"error_code\": \"AUTH_TOKEN_EXPIRED\"}"
  },
  "related_files": ["src/auth/session.py", "src/auth/token.py"]
}

# CI Pipeline
- Run: `npm run test:ci` (outputs structured JSON to .ci-results/)
- If CI fails, read .ci-results/failures.json first
- The `related_files` field points to likely root cause
- Fix the issue and re-run CI before committing

Developer (Slack)
      ↓
Honk AI Agent (分析 Bug)
      ↓
生成修复代码 + PR
      ↓
Verification Loop (MCP Tools)
      ↓
CI 通过？→ 通知开发者 Review
CI 失败？→ Agent 自动读取错误，重试修复

Level 5  ┃ 自主修复    ┃ AI 能自动修一类 Bug，人类只做 Review
━━━━━━━━━╋━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Level 4  ┃ 自动验证    ┃ CI 结构化输出，AI 能读懂失败并自修复
━━━━━━━━━╋━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Level 3  ┃ 机械强制    ┃ Git Hooks + Lint 阻止常见问题
━━━━━━━━━╋━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Level 2  ┃ 基础约束    ┃ CLAUDE.md + 测试覆盖 + Fixture
━━━━━━━━━╋━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Level 1  ┃ 裸奔        ┃ 无文档，无测试，Bug 靠人盯