当 AI 写了全部代码，工程师该干嘛？我把 OpenAI 的答案做成了一个工具

一个有点疯狂的实验

OpenAI 内部有个项目：3 个工程师，5 个月，产出约 100 万行代码，合并了 1500+ 个 PR。几百个内部用户天天用，包括不少重度用户。

听起来没什么特别？关键是这 100 万行代码里，手写的行数是 0。从业务逻辑到 CI 配置到文档，全部由 AI 代理生成。

这不是演示，不是 PPT，是跑在生产环境里的真实产品。

Ryan Lopopolo 把这套方法论写成了一篇文章，叫 Harness Engineering。文章很长，但核心就一句话：

人类掌舵，代理执行。

工程师的工作不再是写代码，而是设计让 AI 能高效产出的环境 —— 上下文怎么组织、规则怎么传达、质量怎么保证。

读完这篇文章我就想：能不能把这套方法论变成一个拿来就用的工具？不用你再去啃原文、自己琢磨怎么落地。直接装上，它就能帮你把项目改造成对 AI 友好的形态。

于是就有了 harness-skills。

不卖关子，它到底干什么

harness-skills 是一个 Claude Code 技能包。安装之后，在 Claude Code 里输入 /harness-engineering 加上你的意图，它就会帮你做这些事：

• 给你的项目打分：你的项目对 AI 代理有多友好？0-10 分，五个维度，告诉你哪里差、哪里好
• 生成 CLAUDE.md：AI 代理进入你项目的第一份"地图"，精简到 100 行以内
• 设计文档结构：怎么组织 docs/ 才不会让文档变成没人维护的僵尸
• 制定黄金原则：给 AI 定规矩——边界校验怎么做、日志怎么打、文件多大要拆
• 创建机械化执行：把架构规则写成 Linter 和 CI 检查，AI 犯规自动拦住
• 搭建代理审查流程：AI 写完代码，另一个 AI 来审，人类只在关键节点介入
• 设置代码垃圾回收：每天自动扫描技术债务，发现问题自动开 PR

听起来挺多？其实核心逻辑很简单。

从十条原则说起

OpenAI 的文章提炼出了十条经过实战验证的原则。我把它们理了一遍，发现可以分成三组来理解：

第一组：怎么喂信息给 AI

P1 上下文是稀缺资源。 AI 的上下文窗口就那么大。你塞一个 500 行的说明文件进去，它处理具体任务的时候反而找不到重点。所以 CLAUDE.md 要控制在 100 行以内，当目录用，不当教材用。

P2 过多指导等于没有指导。 标记了 20 条"重要规则"，AI 一条都不会认真看。只标记前 3-5 条关键的，其余的放到子文档里。

P3 文档会腐烂。 好不容易写完的大一统手册，三个月后就是一堆过时规则的坟墓。解决办法是拆成小文件，加验证状态，用 CI 检查新鲜度。

P4 渐进式披露。 AI 进入项目 → 先看 CLAUDE.md（100 行地图） → 需要架构细节看 docs/architecture.md → 需要领域知识看对应子文档。一层一层展开，别一上来就塞个百科全书。

P6 仓库外的知识等于不存在。 Slack 里讨论的技术决策、Google Docs 里的设计文档——AI 都看不见。所有重要的东西必须落到仓库里。

第二组：怎么管住 AI

P5 执行不变量，不规定实现。 你告诉 AI"所有外部输入必须在 API 边界用 Zod schema 校验"，至于它怎么实现这个校验，让它自己决定。能写成 Linter 的规则，绝不写成文档。

P7 用"无聊"的技术。 越是成熟稳定、文档丰富的库，AI 用得越好。原因很简单——训练数据里见得多。别给 AI 挑战冷门小众库的机会。

P8 持续垃圾回收。 技术债务就像高利息贷款，每天还一点比拖到最后一次性解决靠谱得多。让 AI 每天自动扫描，发现偏差就开重构 PR。

第三组：怎么让流程跑得快

P9 为 AI 的可读性优化。 代码不仅要人看得懂，还要 AI 看得懂。让项目能在 worktree 里独立启动，把日志和指标暴露出来，AI 调试的时候才有抓手。

P10 非阻塞式工作流。 AI 出活的速度远超人类审查的速度。别设一堆审批卡点。改错成本很低，等的成本很高。PR 越短命越好，合并门槛越低越好。

四步流水线

理解了原则，再看工作流就很自然了。这个技能跑的是个四阶段的流水线：

审查 (Audit) → 评估 (Assess) → 生成 (Generate) → 验证 (Validate)

审查阶段扫一遍你项目现在的状态：有没有 CLAUDE.md、docs/ 长什么样、CI 配了什么、用的什么语言框架、什么架构模式。

评估阶段给五个维度打分：上下文管理、文档结构、机械化执行、AI 可读性、工作流设计。然后告诉你最该修的前三个问题和马上能改的速效方案。

生成阶段才是真正动手——你要什么它就生成什么：CLAUDE.md、文档结构、Linter 配置、黄金原则、执行计划模板。

验证阶段交叉检查生成出来的东西和实际代码库是否一致，链接有没有断的，原则有没有自相矛盾的。

举个具体例子。你对它说"生成 CLAUDE.md"，它不是随便给你写个说明文件。它会先扫描整个项目结构，搞清楚你的包依赖关系、测试框架、CI 配置，然后生成一个 100 行以内的地图式文件，里面只放最重要的规则（通常不超过 5 条），剩下的都指向 docs/ 下的子文档。

安装和上手

装起来很简单。在 Claude Code 里执行：

/plugin marketplace add lispking/harness-skills
/plugin install harness-skills@harness-skills

装完就能用了。支持中英文双语触发：

/harness-engineering 审查我的项目
/harness-engineering 生成 CLAUDE.md
/harness-engineering 设计文档结构
/harness-engineering 完整 Harness 设置

也可以用英文：audit my project、generate CLAUDE.md、full harness setup，都能识别。

有一点要注意：这个技能只生成脚手架、文档和工具配置，不会去改你的业务代码。它帮你搭好让 AI 高效工作的环境，不帮你写应用本身。

案例效果

案例一：TypeScript Monorepo 审查

一个包含 3 个 package（@core/api、@core/web、@core/shared）的 TypeScript monorepo 项目，用 pnpm workspace 管理。跑了一次审查：

| 维度             | 得分  | 状态         |
|-----------------|-------|-------------|
| 上下文管理       | 3/10  | 需要改进     |
| 文档结构         | 5/10  | 部分满足     |
| 机械化执行       | 2/10  | 严重不足     |
| AI 可读性        | 4/10  | 需要改进     |
| 工作流设计       | 6/10  | 良好         |

综合评分：4.0/10

识别出的三个核心问题：

1. 没有 CLAUDE.md——AI 代理没有入口
2. 文档是单体 README——注定会过时
3. 没有自定义 Linter——架构约束没保障

对应的速效方案：

1. 立刻生成 CLAUDE.md（约 100 行），上下文管理马上提分
2. 把 README 拆成 docs/ 渐进式结构
3. 加一个分层依赖检查的结构化测试

案例二：生成的 CLAUDE.md 长什么样

还是上面那个项目，生成的 CLAUDE.md 大概这样（节选关键部分）：

# Agent Instructions

## Project Overview
TypeScript monorepo with 3 packages: @core/api, @core/web, @core/shared.
Built with pnpm workspaces. Tests via Vitest.

## Architecture
See docs/architecture.md for the full map.

Rule: Dependencies flow one direction:
  shared → api → web
  Never import from a consumer back into a dependency.

## Critical Rules (must follow)
1. Boundary validation — parse all external data at API boundaries
   with Zod schemas
2. Structured logging — use @core/shared/logger, never console.log
3. No YOLO data access — always validate shapes at boundaries

## Where to Find Things
- Architecture map → docs/architecture.md
- Golden principles → docs/principles.md
- Quality grades → docs/quality.md
- Active plans → docs/plans/
- Decisions → docs/decisions/

注意几个设计决策：只留了 3 条关键规则，架构细节指向子文档，文件总行数控制在 100 行以内。这就是 P1（上下文稀缺）、P2（非指导）、P4（渐进式披露）三条原则的具体落地。

案例三：机械化执行——让 Linter 代替 Code Review

一个常见的痛点：团队约定"shared 包不能依赖 api 包"，但总有 AI 或人不小心违反。靠人 review 捡漏？不靠谱。

生成的 Linter 长这样：

// .linters/layer-dependencies.ts
const LAYER_ORDER = ["shared", "api", "web"];
const FORBIDDEN_IMPORTS = {
  shared: [],       // shared 不依赖任何包
  api: ["web"],     // api 不能依赖 web
  web: [],          // web 可以依赖任何上层包
};

function checkImport(sourceLayer, importPath) {
  const targetLayer = detectLayer(importPath);
  const forbidden = FORBIDDEN_IMPORTS[sourceLayer] || [];
  if (forbidden.includes(targetLayer)) {
    throw new Error(
      `Layer violation: ${sourceLayer} imports ${targetLayer}.\n` +
      `Rule: Dependencies must flow: ${LAYER_ORDER.join(" → ")}\n` +
      `Fix: Move shared logic into a lower layer.`
    );
  }
}

配到 CI 里，每次 PR 自动跑。违反分层规则的代码根本合不进去，不需要人来盯。

案例四：代码垃圾回收——让 AI 自己打扫

这是我觉得最有意思的一个功能。配置一个定时任务，工作日凌晨 3 点自动跑：

# .github/workflows/code-gc.yml
name: Code Garbage Collection
on:
  schedule:
    - cron: "0 3 * * 1-5"  # 工作日 3:00 AM
  workflow_dispatch:

jobs:
  scan:
    steps:
      - name: Check file sizes
        run: |
          # 超过 400 行的文件标出来
          find src -name "*.ts" -exec wc -l {} \; |
            awk '$1 > 400 { print "OVERSIZE:", $2, $1, "lines" }'

      - name: Check for inline helpers
        run: node .linters/detect-duplicate-utils.mjs

      - name: Check boundary validation
        run: node .linters/check-boundary-validation.mjs

      - name: Update quality grades
        run: node .linters/update-quality-grades.mjs

      - name: Open refactoring PR if needed
        run: |
          if git diff --quiet; then
            echo "No issues found"
          else
            git checkout -b gc/code-quality-$(date +%Y%m%d)
            git add .
            git commit -m "chore: automated code quality fixes"
            gh pr create \
              --title "GC: Code quality fixes $(date +%Y-%m-%d)" \
              --body "Automated garbage collection scan results." \
              --label "automated,gc"
          fi

每天自动检查：文件是不是太长了、有没有重复的工具函数、API 边界校验有没有遗漏、质量评分要不要更新。发现问题就自动开 PR，贴上标签。你第二天来上班，review 一下自动开的 PR 就行。

技术债务这个事情，最难的不是还，是记住要还。让 AI 每天帮你记着，这就解决了。

结论

做这个项目的过程中，我反复在想一个问题：AI 编程到底改变了什么？

以前我们说"代码是资产"，但 Harness Engineering 告诉我一个反直觉的结论：在 AI 写代码的世界里，代码反而是廉价的。

你让 AI 重写一个模块，成本几乎为零。真正昂贵的是什么？是上下文、是规则、是让 AI 知道"什么是对的"那个环境。

这就像养一个能力很强但没有常识的新人。他什么都能做，但你需要告诉他哪些坑不能踩、文件放哪里、跟谁确认需求。

Harness Engineering 本质上就是一套"新人培养体系" —— 只不过这个新人是 AI，而且它能同时开 50 个分支并行干活。

harness-skills 把这套"培养体系"封装成了一个即装即用的工具。如果你也在用 AI 编程工具，无论是 Claude Code 还是 Codex 还是 Cursor，都可以试试。至少跑一次审查，看看你的项目在五个维度上拿几分，结果可能会让你意外。

项目地址：github.com/lispking/harness-skills

方法论来源：OpenAI Harness Engineering: Leveraging Codex in an Agent-First World by Ryan Lopopolo