企业官网建设流程全解析

AI 编程工具已经铺天盖地，但大部分人的用法还停留在"开个对话框，让 AI 写一段，复制粘贴，跑不通就再让它改"。说实话，这么用不是不行，但离"工程化"差了十万八千里。我今天想聊的 Harness Engineering，核心就是把 AI 编程从"碰运气"变成"可预期、可复现、可验收"的事情，标题写着"傻子可懂"，不是噱头——我自己就是从完全没头绪的状态摸过来的，这篇教程会把最朴素的那套方法论掰开揉碎讲清楚，再带你完整跑一个项目实战。适合用过 Cursor、Copilot 或 Codex 这类工具但总觉得不踏实的人，也适合想把 AI 编程正经纳入团队工作流的工程负责人。

1. Harness Engineering 是什么：从"AI 能写代码"到"AI 能交付代码"的鸿沟

1.1 先看一个几乎每个人都会遇到的场景

你让 AI 写一个"带分页的用户列表接口"，它十秒钟给你一段看起来非常完整的代码。你复制进项目，跑起来，确实能返回数据。这时候你心里其实有三个问题说不出口：

• 这段代码有没有考虑数据库连接池耗尽的情况？
• 分页参数边界有没有校验？
• 如果明天需求改成"按部门过滤"，这段代码还能不能优雅扩展？

这些问题在传统开发里是基本功，但在 AI 编程的场景下，大多数人直接跳过了。因为 AI 生成代码的过程太顺畅、太像一个"正确答案"了，你会下意识降低警惕。

我见过一个真实案例：一个小团队让 AI 生成了一套用户认证逻辑，本地测试全部通过，结果部署到生产第二天就出了问题——AI 把密码重置的 token 存到了 Redis，但没有设置过期时间。代码是能跑的，但业务逻辑有明显漏洞。这不是 AI 的错，是使用流程里压根没有"让 AI 输出之前先想清楚安全边界"这个环节。

1.2 Harness 的本质：给 AI 装上一副缰绳

Harness 这个英文词本身的意思是"马具、挽具"，引申出来就是"驾驭工具的工具"。放到 AI 编程领域，Harness Engineering 就是一套围绕 AI 编程工具建立的流程、约束和验证机制，目的是让 AI 的输出可预期、可审计、可回滚。

它不是某个具体的软件，也不是某条神奇的提示词。它是一套你自己定义的工作协议。最简单的形态包含四个要素：

• 任务来源：需求是明确地、结构化地传给 AI 的，不是模糊的一句"帮我做个登录"
• 执行边界：AI 知道哪些文件能碰、哪些不能碰，知道验收标准是什么
• 验证关卡：AI 的输出必须通过测试、lint、安全检查才能被接受
• 人工兜底：每一步都有一个人（你）在关键节点做判断

这四个要素拆开看大家都很熟悉，但放进 AI 编程的语境里，它们构成了一个完整的工程闭环。

1.3 为什么现在这个概念突然变得重要

2026 年的 AI 编程工具已经不只是"补全代码"的水准了。以 Codex、Claude Code 为代表的智能体型工具，可以自主读仓库、改多个文件、跑测试、甚至提交 PR。能力上限提高了，风险面也同步变大。

一个能自主改代码的 AI，在没有约束的情况下，就像一匹没戴缰绳的马——跑得快，但方向不可控。我见过有人让代理型 AI 重构整个模块，结果它改了 40 个文件，其中 15 个是无关的格式调整，PR 根本没法审。这不是 AI 笨，是我们没给它缰绳。

Harness Engineering 要解决的问题恰好在这个层面：让 AI 的"自主性"被装在流程里，而不是裸奔。

2. 搭建最小 Harness 的五个组件：从需求到验收的完整闭环

我不喜欢一上来就讲宏大理论，直接从"最小可用"的 Harness 说起。一个能跑的 Harness 至少需要五个组件，而且每个组件都有明确的目的。

2.1 组件一：需求上下文固化

需求是整个链路的起点。你给 AI 的需求写得越像"伪代码+验收标准"，AI 的产出就越可预期。

以"给项目加一个 CSV 导出功能"为例：

需求固化的目的不是限制 AI，而是把"模糊地带"在开工前解决掉。你在需求里写得越具体，后面需要返工的概率就越低。

2.2 组件二：提示词模板沉淀

很多人认为提示词工程就是"把话说清楚一点"，这没错但太浅了。在 Harness 的框架里，提示词模板是可复用的、经过验证的、持续迭代的老物件。

一个相对成熟的提示词模板至少包含这几段：

• 角色定位（你是什么级别的工程师，遵循什么编码规范）
• 任务背景（仓库结构、技术栈、本次需求相关的模块路径）
• 执行约束（不要动哪些文件、不能用哪些依赖、优先复用哪些已有工具函数）
• 输出要求（必须补充测试、必须跑 lint、按什么格式汇报改动）
• 验收标准（想要的结果和可量化的指标）

我习惯把模板拆成两块。一块是项目级模板，每个项目一套，写清楚技术栈和约定；一块是任务级模板，每次在项目级模板基础上追加本次需求的具体说明。两级模板在 Harness 中分别承担"稳定的基准"和"可变的任务描述"两个职责，缺一不可。

2.3 组件三：人工检查清单：AI 的盲区和人性的惰性

这是整个 Harness 里最容易被忽略、也是最值钱的一环。

AI 生成代码最常见的盲区有三个：

• 安全边界：权限校验、输入校验、敏感信息泄露
• 异常处理：AI 倾向于写"happy path"代码，对异常分支覆盖不足
• 非功能性需求：性能、可观测性、日志规范，AI 很少主动考虑

对于这些问题，你不可能指望 AI 自觉，所以要用人工检查清单来补位。

我推荐的做法是：在需求模板里预置一栏"本次改动必须审查的点"，每次 AI 完成后，你拿着这个清单逐项对照，而不是泛泛地看代码。清单可以非常简单，比如：

• 新增接口是否继承现有的鉴权装饰器？
• 是否处理了空数据和边界值？
• 是否补充了对应的单元测试？
• 日志是否包含足够的上下文？

别小看这几条。我在这套体系里发现，有清单和没清单，审查效率差三倍以上。没有清单的时候，你会被 AI 输出的"流畅感"带着走；有了清单，你只做黑盒验收，反而更快。

2.4 组件四：自动化验证闸门

人工检查解决"方向对错"，自动化验证解决"代码能不能跑、质量过不过关"。Harness 的第四个组件是在你的项目里预设一套自动化闸门，AI 的改动必须通过闸门才能进入下一步。

这些闸门可以包括：

• 静态检查（ESLint / Ruff / golangci-lint）
• 单元测试（Pytest / JUnit，视项目而异）
• 构建验证（能完整地打包成部署产物，而不是只在编辑器里编译通过）
• 类型检查（TypeScript / mypy）

值得注意一点：这些闸门不应该由 AI 自己来开。在很多工具里，AI 可以自动跑测试甚至修改测试来让它通过——这在调试阶段是好事，在验收阶段就是隐患。闸门的运行命令、判定逻辑和记录结果，应该由你（或 CI）来掌控，并由你来认定"是否通过"。这不是对 AI 不信任，而是职责分离的基本要求。

2.5 组件五：变更记录与回滚预案

最后一个组件，是让 Harness 这个系统本身能持续演进的东西。

每次 AI 完成一次任务，建议顺手记录三件事：

• 需求描述和所用提示词模板的版本
• AI 产出的核心改动摘要，以及过程中发现的反复项
• 失败点：哪些地方 AI 第一次没做对，它是如何被纠正的

这些记录会沉淀成两个输出：一个是你的提示词模板的迭代依据，另一个是你的典型坑位清单——比如"这个项目里 AI 经常漏掉 Redis 的 key 过期时间，审查时必须重点盯"。

同时，建议在需求接入 AI 之前就确认回滚方案。对于改动范围大的任务，提前给 Git 打好标签，或者在功能级别上确保可下线。AI 写代码再快，也不该让你的发布流程为此承担额外风险。

3. 实战演示：用免费的 Codex CLI 从零跑通一个 Harness 流程

理论基础说了一堆，接下来用一个真实的例子把它串起来。我用的是 OpenAI 的 Codex CLI（当前很多团队都在用的能自由配置的 AI 编程工具，浏览器搜索 codex 就能找到入口，安装方式在官方文档里写得很清楚，这里不赘述），而且以下流程用的不是复杂的团队级系统，而是一个单人也能跑通的最小 Harness。

3.1 项目目标与需求定义

为了演示而不涉及任何具体的业务代码授权问题，我拿一个本地环境就能完整的项目来说事。

目标仓库结构：

my-report-service/ ├── main.py ├── config.py ├── requirements.txt └── README.md

需求描述（直接作为任务级提示词的主体）：

• 在 main.py 中新增一个 FastAPI 接口：GET /api/reports/export
• 接口读取查询参数 start_date 与 end_date，日期格式为 YYYY-MM-DD
• 如果参数缺失或时间范围超过 90 天，返回 400 错误和 JSON 提示
• 模拟数据从 config.py 中读取（一个简单的 Python 字典常量），导出为 CSV 并作为响应返回
• 下载文件的文件名建议为 reports_YYYYMMDD.csv
• 必须使用 FastAPI 自带的 Response 类来实现下载头
• 不能引入新的第三方依赖

这个需求里包含了接口形态、参数规格、边界条件、依赖约束、输出格式五个层面的要求，AI 没有太多自由发挥空间。让 AI 少自由发挥，不是要扼杀它的能力，而是把创造力留给真正需要的地方。

3.2 项目级模板与任务级模板的拼接

先用项目级模板交代背景：

你是这个 Python 服务的高级开发。项目结构：main.py 是入口，config.py 放配置项和模拟数据。代码风格遵循 PEP 8。 在每次任务中，保持现有模块最小改动，按需补充类型标注。新增代码后必须自己先检查一遍是否有明显错误。 执行前先说明你的计划，执行后报告改动摘要。

然后接任务级模板（即上面的需求定义），拼成完整的提示词。我不主张把提示词写得像八股文，能自然衔接就好。关键是让 AI 在动手前先复述计划，而不是直接丢代码——这个动作能提前暴露它对需求的理解偏差。

3.3 Codex CLI 运行链路与人工关卡设计

打开 Codex CLI 进入项目目录，把上面拼接好的提示词一次性发给它。注意观察两点：

• 它有没有在动手前给出执行计划
• 它是不是只改了描述中提到的文件，有没有顺手动别的东西

实测中，Codex CLI 在大多数情况下会先描述方案再动手。如果它跳过了计划直接写代码，我一般会停下来，追加一条"先把执行计划列出来，等确认后再写代码"，让整个流程回到 Harness 规定的节奏上。

AI 改完代码后，进入验证阶段。我在本地跑三个命令：

# 检查语法与基础风格 python -m py_compile main.py config.py # 启动服务并测试正常链路 uvicorn main:app --port 8000 & curl "http://127.0.0.1:8000/api/reports/export?start_date=2026-08-01&end_date=2026-08-31&_=0" # 测试异常链路 curl "http://127.0.0.1:8000/api/reports/export?start_date=invalid&end_date=2026-08-31&_=0"

第一行命令是最基础的 Python 编译校验，确保没有语法错误。第二行验证正常链路返回 CSV。第三行验证异常参数能否返回 400。

这种绿路+红路双验证的思路很简单，也容易被跳过。很多人只测试正常链路，看到 CSV 出来了就结束，但 AI 工程化的重点恰恰在于负向路径。在 Harness 里，红路测试是卡口的一部分，跟绿路同等重要。

3.4 审查清单在执行中的实际运用

AI 输出代码和测试结果后，拿审查清单逐项过：

• 接口有没有按需求使用 FastAPI 的 Response 或 StreamingResponse？还是用了其他方式？
• start_date / end_date 的缺失、格式错误、范围超限是否都走统一的 400 响应？
• CSV 的列头和数据内容是否是从 config.py 读出来的？

实测中，Codex CLI 实现的接口基本符合需求，但有一个细节它差点漏掉：当 start_date 缺失时，它返回的是 422（FastAPI 默认校验错误），而不是需求要求的 400。这个差异如果不拿清单去对，很容易被忽略。修正方式也很简单，在需求里加一句"无论参数缺失还是格式错误，都必须返回 400 和业务错误码"，AI 就能改对。

这个案例很有代表性——AI 会默认遵从框架本身的规则，而不是你心里的业务规则，而 Harness 的检查清单恰恰补上了业务规则的定义与验证。

通过上面这一节，你可以看到：把 Harness Engineering 落到一个真实项目里，其实不需要平台、不需要什么高级基建，只要一套可重复的流程，以及你在关键节点的把关。流程跑得顺了，AI 编程的效率优势才能真正变成工程效率。

4. 团队落地 Harness Engineering 的三种模式

个人跑通以后，下一步通常就是把这一套推到团队里去。但不是所有团队都需要同一个重量的 Harness，不同阶段有不同方案。

4.1 模式一：个人工作流（适合个人开发者、自由职业者）

这个模式最简单，就是按照第 2 节的内容，把五个组件动手做出来，并且坚持用三个迭代周期以上。

关键点在你的"主线仓库"和"实验仓库"分离，不要让 AI 直接修改你依赖的主仓库。自由职业者最容易犯的错误是：在真实客户项目上急急忙忙用 AI 改代码，改错了连回滚都手忙脚乱。建议用私人实验仓库反复跑需求到验收的循环，流程稳定了，再戴着 Harness 去碰客户项目。

4.2 模式二：小团队轻量模式（适合 2-10 人团队）

小团队的第一个诉求通常是"要让 AI 高效率地写代码，同时不造成混乱"，最适合的方向是把 Harness 的组件固化到流程文档和仓库配置里。

具体做法可以是：

• 在仓库目录下放一个 AGENTS.md 或类似文件，写明项目技术栈、目录约定、禁止改动的模块、以及代码风格要求
• 用普适的格式搞一个 issue template，里面预置需求描述、验收标准、检查清单等字段
• 把 CI 配置好，AI 分支的改动必须通过 lint、typecheck、test 才能合并

这个阶段的核心是"规则写进仓库"，因为文件就是契约，AI 每次动手前也会先读仓库内的规则。

4.3 模式三：团队级 Harness 平台（适合中大型组织、规范要求高的团队）

当地规模到了数十人，AI 的使用密度很高以后，靠文档约束会显得不够。这时候可以在已有工程基础设施（GitLab 或 GitHub）之上做三层补充。

• 流程设施层：统一的需求模板、评审模板、AI 使用流程
• 工具设施层：统一的 Agent 配置，公共的 prompt 模板库（按业务域维护），统一 Code Review Bot 配置
• 度量设施层：统计 AI 辅助产生的 PR 的缺陷率、返工率、合并耗时等

度量这层很多团队没做，但这恰恰是 Harness Engineering 里最有价值的部分——只有度量了，你才知道这套"缰绳"到底是在提升效率还是拖慢节奏。

我见过一个团队在推行时的主要争论是"要不要让 AI 直接提交 PR"。有人觉得这是效率最大化，有人觉得不可控。我的看法是：在 Harness 成熟之前，让 AI 只负责生成改动和建议，提交动作必须由人工完成。等运行一两个月、返工率稳定可控了，再逐步开放更高级别的自主权。护城河不是限制 AI，而是知道怎么一点一点放权。

4.4 从个人到团队的常见过渡误区

推 Harness 时最常出现的问题是把工具当流程。团队负责人下载了一个很酷的 Agent，配好了一堆参数，但需求不写清楚、检查清单形同虚设、测试跑不跑全看心情——那 Harness 就是一张虎皮，实际没有任何作用。

反过来说，如果你的工具一般，但需求、审查、验证三个环节都严格执行了，流程的有效性是远超前者的。

5. 我把 Harness 用在真实项目里之后，踩过的几个坑

从"会用 AI 编程"到"有 Harness 地使用 AI 编程"，中间有一段必经的适应期。这里挑几个我身上发生过的典型问题，你可以当成提前预警。

5.1 坑一：AI"过度自信"造成的假阳性，该怎么防

有次我让 Codex CLI 给一个模块补测试，它跑完报告"全部通过"。我没复查，直接合并了。后来才发现它把某个断言参数写错了，压根没测到目标函数。

从那以后我定了一条铁律：测试类改动必须由人来看测试代码本身，而不仅仅是看结果表格。AI 报绿的时候，我们要意识到这个绿有多少可信度。可以试着让 AI 在测试文件里明确给出"为什么这个测试能抓到目标 bug"的解释，解释不清楚就退回重写。

5.2 坑二：上下文太长之后，AI 会"选择性失忆"

有一次需求涉及多个文件的修改，我把所有相关文件内容都贴进了提示词。结果 AI 前期还很听话，改到一半突然开始用错误的旧变量名，后面越改越乱。

后来我在 Harness 里增加了一条进度回调规则：如果一个任务的改动预计超过三个文件，就让 AI 每完成一个阶段报告一次中间状态，我来确认是否继续。这样上下文被拆散到多轮对话里，AI 反而在每轮都表现得更稳。

5.3 坑三：提示词模板变成了噪音，需要定期"断电清理"

我的提示词模板一开始写得非常全面，加了很多项目专属的约定。但用了几周后发现，AI 每次通读模板都会产生大量无效考虑，响应速度变慢、重点模糊。

后来我把模板做了一次减法，只保留"会直接改变 AI 行为"的内容。哪些内容会改变行为？规则条目、约束清单、验收标准。哪些不会？关于项目价值的大段背景描述。背景信息只保留在需求正文里，模板里干干净净，反而效果好很多。

5.4 坑四：拿"代码通过率"当 KPI

有一个普遍倾向：团队推进 AI 编程时，喜欢统计"AI 生成的代码有没有一次通过"。这个指标其实没太大意义——因为你可以通过疯狂写冗余测试来刷高通过率，或者通过让 AI 只做简单任务来保证指标好看。

更值得度量的是"单位交付时间的下降幅度"和"缺陷逃逸率的变化"。换句话说，看整个链路的产出质量，而不是某个工序的一次成功率。

6. 我个人的实际体会，以及一套可以直接抄的起步建议

AI 编程工程化这件事，我现在的理解可以浓缩成一句话：它不是为了限制 AI，而是为了保护你使用 AI 的勇气。没有 Harness 的时候，你每次让 AI 改代码都是一次赌博；而有了 Harness，变成了一个你可以放心托付的执行者——即使出问题，也能快速定位、快速兜底。

给刚开始走这条路的人一个务实的起步建议：

• 第一周，不要追求完美模板，先用第 2 节的最小五件套，把一次需求从提报到验收完整地走下来
• 第二周，记录所有返工的根因，并把高频坑位写进检查清单
• 第三周以后，逐步增加验证关卡，把可自动化的部分交给检测工具

我现在的 Harness 已经跑了几个月，最大的收获不是代码写得快了多少，而是"让 AI 干活"这件事本身变得很有底气。今天周五下午，我让 Codex 改了一个跨 12 个文件的依赖升级，中间它自己跑了两轮测试、提交了报告，我在关键节点做了三次确认，六点多就合入主干。放在一年前，这是我周五忙到深夜才能完成的工作量。

最后分享一个我一直在用的小习惯：给自己准备一个"Harness 复盘笔记"，每次 AI 的改动出了幺蛾子，就记录失败点、提示词版本、修复方式。这几个月下来，它已经成了我最重要的个人资产之一——比任何提示词模板都值钱。因为 AI 的工具会一直更新，模型会越来越强，但你对"如何驾驭它"这件事的理解，才是真正随着经验增长的复利。这篇日志，就是你的 Harness 从版本 0.1 走向 v1.0 的轨迹。