从零构建一个 Harness-on-the-Loop 系统

前 16 章我们建立了一个完整的理论体系：四阶演进模型、Harness 三层架构、围栏工程四大支柱、执行层三大机制、多 Agent 协作三大支柱、Meta-Harness 自进化循环。但对于一个实际的开发团队来说，一个常见的问题是：“我应该从哪里开始？不可能一次性构建所有这些东西。”答案是渐进式构建——从最基础的 Rules 开始，逐步添加 Hooks、沙箱、状态机、多 Agent 协调，每一步都有可交付的价值。本章将通过一个具体的实战场景——为一个中型 Web 项目搭建 Harness-on-the-Loop 系统——来演示这个渐进式构建过程。实战场景项目背景：技术栈：TypeScript + Next.js + Prisma + PostgreSQL团队规模：5 人代码规模：约 200 个文件，15K 行代码痛点：Agent 生成的代码经常破坏架构边界、引入安全漏洞、不遵守团队规范阶段一：基础围栏（1-2 小时）Step 1：编写 CLAUDE.md# CLAUDE.md ## 项目概述 这是一个 SaaS 管理后台，使用 Next.js + Prisma + PostgreSQL。 ## 架构规则 - 分层架构：Route Handler → Service → Repository → Prisma - Route Handler 不直接调用 Prisma，必须通过 Service 层 - Repository 层不 import Service 层或 Route Handler 层 - 所有 API 输入必须通过 Zod schema 验证 ## 编码规范 - 使用 TypeScript strict 模式 - 函数命名：camelCase - 类型命名：PascalCase - 常量命名：UPPER_SNAKE_CASE - 使用 named export，不使用 default export ## 安全规则 - 不在代码中硬编码 API Key、数据库密码等敏感信息 - 所有数据库查询使用 Prisma 参数化查询，不拼接 SQL - 不在客户端代码中暴露服务端密钥 ## 测试规则 - 每个 Service 函数必须有对应的单元测试 - 每个 API 端点必须有对应的集成测试 - 测试文件放在 __tests__/ 目录下，与源文件结构一致价值：Agent 立即获得了项目的行为规范。虽然这是概率性约束，但已覆盖 80% 的常见问题。Step 2：配置基础 Hooks{"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":".claude/hooks/block-secrets.sh"},{"type":"command","command":".claude/hooks/block-dangerous-commands.sh"}]}],"PostToolUse":[{"matcher":"Write|Edit","hooks":[{"type":"command","command":"npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""},{"type":"command","command":"npx eslint --fix \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 21 || true"}]}]}}价值：从这一刻起，Agent 的每一个 Bash 命令都会被检查是否包含凭证，每一次文件写入都会被自动格式化和 Lint。这是确定性保证——不会被绕过。阶段二：架构守护（2-4 小时）Step 3：架构测试创建__tests__/architecture.test.ts：import{execSync}from'child_process';describe('Architecture Rules',()={test('Route Handlers should not import Prisma directly',()={constresult=execSync('grep -r "from.*prisma" src/app/api/ --include="*.ts" | grep -v ".test.ts"',{encoding:'utf-8',stdio:['pipe',