传统软件工程：人写代码 → AI 辅助
Harness Engineering：人设计流程 → AI Agent 写代码 → 人审核

# .claude/harness.yaml — Harness Engineering 配置模板
project:
  name: my-saas-app
  type: web-application
  tech_stack: [Next.js, TypeScript, Prisma, PostgreSQL]

workflows:
  # 工作流1：新功能开发
  feature:
    steps:
      - name: 需求文档化
        prompt: |
          根据以下一句话需求，生成一份结构化的功能规格文档：
          - 用户故事
          - 验收标准（BDD格式）
          - 涉及的数据库表变更
          - API端点设计
          不要写代码，只输出文档。
        output: docs/features/{feature-name}.md

      - name: 代码生成
        prompt: |
          阅读 docs/features/{feature-name}.md，严格按照规格实现完整功能。
          要求：
          1. 先写测试，再写实现
          2. 每个文件完成后用 `npm run typecheck` 验证
          3. 每完成一个模块，commit 一次
        auto_commit: true

      - name: 自检
        prompt: |
          对刚才实现的所有代码进行自我审查：
          1. 是否有安全漏洞（SQL注入、XSS、未授权访问）？
          2. 是否有未处理的边界情况（空值、超长输入）？
          3. 测试覆盖率是否≥80%？
          输出审查报告到 docs/reviews/{feature-name}-review.md

  # 工作流2：Bug修复
  bugfix:
    steps:
      - name: 根因分析
        prompt: |
          分析以下bug报告，输出根因分析（Root Cause Analysis）：
          - 触发条件
          - 影响的代码路径
          - 修复方案（至少2个备选）
        output: docs/bugs/{bug-id}-rca.md

      - name: 修复+测试
        prompt: |
          实施 docs/bugs/{bug-id}-rca.md 中的方案1。
          注意：先写回归测试验证bug确实存在，再修复，最后确认测试通过。

quality_gates:
  # 质量门槛：不通过的代码不允许 commit
  - name: TypeScript类型检查
    command: npm run typecheck
  - name: Lint检查  
    command: npm run lint
  - name: 测试覆盖率
    command: npm test -- --coverage --threshold 80

# 启动 Claude Code，加载 harness 配置
claude --harness .claude/harness.yaml

# 在 Claude Code 会话中，直接用斜杠命令启用工作流
/harness feature --name "用户登录与注册"

你是一个全栈工程师，负责实现以下功能：[功能描述]

执行步骤：
1. 【规划阶段】先分析需求，列出需要创建/修改的文件清单（不要写代码）
2. 【确认阶段】等我回复"继续"后，再开始写代码
3. 【实现阶段】逐个文件实现，每个文件完成后用 ${BUILD_CMD} 检查编译
4. 【测试阶段】为每个新增的API端点编写集成测试
5. 【文档阶段】更新 README 和相关API文档

约束条件：
- 遵循项目现有的代码风格和目录结构
- 所有数据库操作使用 Prisma ORM，禁止写原始SQL
- API响应格式统一为 { code: number, data: any, message: string }
- 每个文件不超过 300 行（超出则拆分）

审查以下代码变更，按检查清单逐项打分（1-5分）：

检查清单：
1. [ ] 安全：是否存在注入、越权、敏感信息泄露？
2. [ ] 边界：空值、超长输入、并发冲突是否已处理？
3. [ ] 性能：是否存在 N+1 查询、未加索引的查询？
4. [ ] 可维护性：命名是否清晰？是否有硬编码魔法数字？
5. [ ] 测试：关键路径是否有测试覆盖？

输出格式：
- 总分：X/25
- 严重问题（阻塞合并）
- 改进建议（建议修复）
- 亮点（做得好的地方）

扫描当前代码仓库，识别技术债务。按以下维度分类：

1. 过时依赖：package.json 中超过6个月未更新的依赖
2. 代码重复：相似度>80%的代码块
3. 未处理 TODO/FIXME：标注但未解决的临时代码
4. 类型安全漏洞：any 类型使用、类型断言（as）滥用

输出到 docs/tech-debt-$(date +%Y%m%d).md，按优先级排序。

Harness Engineering 团队（3人）
  │
  ├── 需求定义层：用结构化Prompt描述功能需求
  │     └── 输出：Spec文档 + 验收标准
  │
  ├── Agent调度层：Codex Agent 集群并行执行
  │     ├── Agent A: 负责应用逻辑（CRUD、业务规则）
  │     ├── Agent B: 负责基础设施（Terraform、K8s配置）
  │     ├── Agent C: 负责工具链（CI/CD脚本、lint规则）
  │     ├── Agent D: 负责文档（README、API文档、架构图）
  │     └── Agent E: 负责内部工具（Admin面板、监控Dashboard）
  │
  └── 质量把关层：自动化测试 + 人工审核关键路径

# 不要这样
$ claude "给我做一个SaaS产品"

# 应该这样
$ claude --harness .claude/harness.yaml
/harness feature --name "用户认证" --require-approval

# 在 harness.yaml 中添加上下文管理
context_management:
  strategy: summary_chain
  max_files_per_agent: 12
  summary_prompt: |
    总结当前步骤的关键决策：
    1. 做出的架构选择
    2. 定义的接口约定
    3. 已知的技术债务
    输出到 .context/{workflow}-{step}.md

# harness.yaml 中添加分支策略
branch_strategy:
  pattern: "agent/{workflow}/{feature-name}-{timestamp}"
  auto_stash_before_branch: true