夜雨聆风
AI 编程铁三角:03 Harness Engineering 入门
模型是给定的，Harness 才是你能控制的
一个令人沮丧的场景
某天，你让 AI 助手帮你重构一个模块。
3 小时后，你发现：
✓ 功能实现了✗ 代码风格和项目不一致（它用了 camelCase，你用 snake_case）✗ 目录结构被它改了（新增了 utils/helper.py）✗ 测试文件被它删了（「我觉得不需要」）✗ 留下了 10 个 TODO 注释（「后续优化」）你问 AI：为什么这样改？
AI：我觉得这样更好…
问题：AI 有能力，但没有边界。
这就是 Harness Engineering 要解决的问题。
Harness Engineering 是什么
一句话定义：
Harness Engineering = AI Agent 的约束系统工程
核心理念
Agent = Model + HarnessModel（模型）= 马，提供能力Harness（约束）= 缰绳，提供边界你控制不了马的能力（模型是给定的）但你可以设计缰绳（Harness 是你能控制的）
反直觉的洞察
很多人认为：
约束越多，AI 越不自由，效率越低
事实恰恰相反：
约束越清晰，AI 越确定该做什么，效率越高
例子：
无约束场景：AI：这个数据结构用 dict 还是 list？自己猜一个吧 这个函数要不要加缓存？先加上再说 这个模块放哪个目录？随便放一个有约束场景：AI：CLAUDE.md 说「使用 dict 存储配置」 「所有 I/O 操作都要加缓存」 「工具函数放在 src/utils/」→ 不用猜，直接做，效率更高三大支柱
Harness Engineering 由三大支柱组成：
支柱一：Context Engineering（上下文工程）
核心问题：AI 看不到的信息等于不存在
|
|
|---|
|
|
实践要点：
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
支柱二：Architectural Constraints（架构约束）
核心问题：如何给 AI 画清晰的边界
|
|
|
|---|---|
|
|
src/fetchers/
|
|
|
snake_case
|
|
|
|
|
|
|
|
|
|
实践要点：
-
CLAUDE.md 定义核心约束 -
测试套件验证约束 -
Pre-commit Hook 自动检查
支柱三：Entropy Management（熵管理）
核心问题：系统如何长期保持健康
|
|
|
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
熵增的表现：
-
代码风格不一致 -
目录结构混乱 -
测试覆盖率下降 -
文档过时
实战案例：为 hot-trends CLI 搭建 Harness
背景
hot-trends 是一个 Python CLI 工具，用于抓取热榜文章并筛选 AI 相关内容。来自于前两篇AI 编程铁三角：01 Superpowers 入门AI 编程铁三角：02 OpenSpec 入门的案例，完成 Harness 的搭建。
Level 1 Harness：5分钟搭建基础约束
Level 1 是最轻量的 Harness，只需要 CLAUDE.md + 测试 + Hook。
第一步：编写 CLAUDE.md
在项目根目录创建 CLAUDE.md，定义项目的核心约束：
💡 如果你用 Claude Code。你用 /init 命令会自动扫描项目，识别技术栈、目录结构、常用命令生成CLAUDE.md的基础骨架。
## 项目概述Hot-Trends CLI 是一个 Python 命令行工具，主要用于抓取并筛选来自中文技术社区（掘金、知乎）的 AI 相关文章。它可以在终端中以表格形式展示结果，并支持导出为 JSON 或 Markdown 格式。## 开发命令\`\`\`bash# 安装依赖（可编辑模式）pip install -e .# 运行所有测试pytest tests/ -v# 运行单个测试文件pytest tests/test_fetcher.py -vpytest tests/test_filter.py -vpytest tests/test_output.py -v# 本地运行 CLI（安装后）hot-trendshot-trends -l 100 -vhot-trends -o output.json# 不安装直接运行 CLIpython -m src.main\`\`\`## 架构设计### Fetcher 模式项目使用基类模式来管理数据源：- `src/fetchers/base.py` - `BaseFetcher` 抽象类，定义接口- `src/fetchers/juejin.py` - `JuejinFetcher` 实现掘金 API（支持分类）- `src/fetchers/zhihu.py` - `ZhihuFetcher` 实现知乎热榜抓取新增数据源应继承 `BaseFetcher` 并实现 `fetch_hot_trends(limit)` 方法，返回 `List[Article]`。### 数据流1. `main.py` 解析 CLI 参数，根据 `--source` (juejin/zhihu/all) 协调 fetchers2. 从选定的 fetchers 收集文章3. `AIFilter.filter_articles()` 按 AI 关键词过滤（可通过 `-k` 自定义）4. `OutputFormatter` 显示表格，并可选择保存到文件### 核心类- `Article` (models.py) - 数据类，包含 `to_dict()` 方法用于序列化- `AIFilter` (filter.py) - 基于关键词的过滤，带默认 AI 词库- `OutputFormatter` (output.py) - 处理终端表格（rich）、JSON 和 Markdown 输出## CLI 参数| 参数 | 说明 ||------|-------------|| `-l, --limit` | 文章数量（默认：50） || `-o, --output` | 输出文件（.json 或 .md） || `-s, --source` | 数据源：juejin/zhihu/all（默认：juejin） || `-c, --category` | 掘金分类：backend/frontend/ai 等（默认：all） || `-k, --keywords` | 自定义关键词（逗号分隔，追加到默认值） || `-v, --verbose` | 详细日志 |## 项目结构说明- 测试使用 pytest fixtures 和 tmp_path 进行文件操作- `openspec/` 目录包含使用 OpenSpec 格式的变更提案（非核心代码）- Husky 通过 package.json 配置 git hooks（虽然这是 Python 项目，但可以用 npm 管理 Git Hooks）关键点：CLAUDE.md 应该”刚好够用”，覆盖核心决策点即可。这个配置适用于 hot-trends 这类 Python CLI 项目，你可以根据自己的项目调整。
第二步：配置 Pre-commit Hook
Husky 是一个 Git Hook 管理工具，让你在提交代码前自动运行检查和测试。
安装 Husky（以 npm 项目为例）：
npm install- D huskynpx husky inithusky init 会自动生成 .husky/pre-commit 文件，默认内容只有：
npm test对于 Python 项目，你可以编辑 .husky/pre-commit，增强 Hook 检查：
# Python 项目示例pytest tests/ -v# 运行测试flake8 src/ # 代码风格检查black --check src/ # 代码格式化检查这样每次提交代码时，都会自动验证代码质量、测试通过率和类型安全。
第三步：验证测试套件
hot-trends 项目在前两篇文章中已经创建了完整的测试套件：
tests/├── test_fetcher.py # 数据获取器测试（4个测试）├── test_filter.py # AI过滤器测试（7个测试）└── test_output.py # 输出格式化器测试（3个测试）验证测试是否正常工作：
pytest tests/ -v应该看到类似输出：
tests/test_fetcher.py::test_fetcher_initialization PASSED [ 7%]tests/test_fetcher.py::test_fetcher_with_custom_params PASSED [ 14%]tests/test_fetcher.py::test_fetch_hot_trends_success PASSED [ 21%]tests/test_fetcher.py::test_fetch_hot_trends_failure PASSED [ 28%]tests/test_filter.py::test_default_keywords PASSED [ 35%]tests/test_filter.py::test_custom_keywords PASSED [ 42%]tests/test_filter.py::test_is_ai_related_by_title PASSED [ 50%]tests/test_filter.py::test_is_ai_related_by_tags PASSED [ 57%]tests/test_filter.py::test_not_ai_related PASSED [ 64%]tests/test_filter.py::test_case_insensitive PASSED [ 71%]tests/test_filter.py::test_filter_articles PASSED [ 78%]tests/test_output.py::test_save_json PASSED [ 85%]tests/test_output.py::test_save_markdown PASSED [ 92%]tests/test_output.py::test_print_table PASSED [100%]============================================== 14 passed in 0.24s ===============================================💡 为什么需要测试？
Hook 会在提交前自动运行测试 如果测试失败，提交会被阻止 这确保了代码质量，防止有 bug 的代码进入仓库
如果没有测试怎么办？
如果你的项目还没有测试，可以先创建一个简单的冒烟测试：
# tests/smoke_test.pydeftest_smoke():"""冒烟测试 - 确保测试框架正常工作"""assertTrue验证 Level 1 Harness
完成以上三步后，即使有 CLAUDE.md，AI 也不会自动遵循 Harness 流程。
要让 AI 真正遵循 Harness 流程，需要：
-
1.在对话开始时明确声明 – 每次开始新任务时，主动说明将遵循 Harness Level 1 流程 -
2.使用技能系统 – 通过 Skill 工具调用相关的 Harness 规范 -
3.设置 Git Hooks – 在提交前强制检查是否遵循了流程
我们先用第一种方式在对话前声明（长期使用按第二种方式新增一个 Skill）：
你：请按照 Harness Engineering Level 1 流程来完成这个任务：1. 先读取 CLAUDE.md 了解项目规范2. 查看相关代码和测试文件3. 先写测试（TDD）4. 实现功能5. 运行测试验证6. 更新文档任务：帮我优化输出格式，支持 CSV 导出AI：（Step 1: 读取上下文） ✅ 已读取 CLAUDE.md 了解项目规范 ✅ 已查看 src/output.py、src/models.py、src/main.py ✅ 已查看 tests/test_output.py 了解测试模式 关键发现： - 现有输出格式：JSON、Markdown - OutputFormatter 类已有 save_json() 和 save_markdown() 方法 - 测试使用 pytest fixtures 和 tmp_path - CLI 参数通过 argparse 解析 （Step 2: 测试驱动开发 TDD） 先编写测试用例（功能实现前）： 在 tests/test_output.py 中添加： ```python def test_save_csv(formatter, sample_articles, tmp_path): """测试CSV导出""" filepath = str(tmp_path / "test.csv") formatter.save_csv(sample_articles, filepath) assert os.path.exists(filepath) with open(filepath, 'r', encoding='utf-8-sig') as f: content = f.read() # 检查CSV头部 assert "排名,标题,作者,来源,链接,阅读量,点赞,评论,标签" in content # 检查数据行 assert "GPT-4使用指南" in content assert "张三" in content assert "1" in content assert "2000" in content assert "掘金" in content ``` 验证测试失败（TDD 原则）： $ pytest tests/test_output.py::test_save_csv -v FAILED - AttributeError: 'OutputFormatter' object has no attribute 'save_csv' ✅ 测试如预期失败，因为 save_csv 方法还未实现 （Step 3: 实现功能） 在 src/output.py 中实现： 1. 导入 csv 模块 2. 新增 save_csv() 方法 - 使用 utf-8-sig 编码确保 Excel 兼容 - CSV 列名使用中文 - 标签使用分号分隔 3. 更新 format_output() 方法支持 CSV 在 src/main.py 中更新 CLI 参数： - 更新 -o/--output 帮助文本 - 在 -f/--format choices 中增加 'csv' - 更新帮助信息示例 （Step 4: 验证测试） 运行测试验证： $ pytest tests/test_output.py -v tests/test_output.py::test_save_json PASSED [ 20%] tests/test_output.py::test_save_markdown PASSED [ 40%] tests/test_output.py::test_print_table PASSED [ 60%] tests/test_output.py::test_save_csv PASSED [ 80%] ← 新增 tests/test_output.py::test_format_output_with_csv PASSED [100%] ← 新增 $ pytest tests/ -v collected 16 items ... (所有测试通过) ============= 16 passed in 0.25s ============== ✅ 所有 16 个测试全部通过，包括新增的 2 个 CSV 测试 实际运行 CLI 验证： $ python -m src.main -l 10 -o /tmp/test_ai_articles.csv -v 🚀 开始抓取热榜... 📊 抓取掘金热榜... ✅ 获取 10 篇掘金文章 🎯 筛选出 5 篇AI相关文章 ✅ 已保存到: /tmp/test_ai_articles.csv ✅ CSV 文件成功生成，包含完整的文章数据 （Step 5: 更新文档） 更新 CLAUDE.md： - 项目概述：增加 CSV 格式支持说明 - 核心类描述：增加 CSV 输出 - CLI 参数表格：增加 -f 参数说明 ✓ 任务完成！关键点：AI 不再是“自由发挥”，而是基于明确的约束进行开发。这就是 Harness 的力量！
Level 1 效果对比
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
关键改进：
-
AI 不再“自由发挥”，而是基于明确约束开发 -
每次提交都自动验证，问题早发现早解决 -
项目长期保持健康状态
Level 2 Harness：动态约束与自动化
Level 2 在 Level 1 基础上增加 动态上下文 和 更多 Hook，让 AI 能感知项目实时状态。
增加动态上下文
动态上下文是指那些会随时间变化的项目状态信息，AI 需要了解这些实时信息才能做出更准确的决策。
静态上下文（不变或很少变化）：├── CLAUDE.md ← 项目约定、架构设计├── 代码规范 ← 命名规则、代码风格└── 目录结构 ← 文件组织方式动态上下文（经常变化）：├── Git 分支 ← 当前在哪个分支├── 修改的文件 ← 哪些文件被改动了├── 测试状态 ← 测试是否通过├── 依赖版本 ← 安装了哪些包└── 运行环境 ← Python/Node 版本等创建脚本自动生成项目当前状态信息，让 AI 了解实时环境：
#!/bin/bash# scripts/generate_context.shecho"# 项目动态上下文"> CONTEXT.mdecho"">> CONTEXT.mdecho"生成时间: $(date)">> CONTEXT.mdecho"">> CONTEXT.md# Git 信息echo"## Git 状态">> CONTEXT.mdecho"- 当前分支: $(git branch --show-current)">> CONTEXT.mdecho"- 最后提交: $(git log -1--oneline2>/dev/null ||echo'无')">> CONTEXT.mdecho"- 未提交修改:">> CONTEXT.mdgit status --short2>/dev/null |sed's/^/ - /'>> CONTEXT.mdecho"">> CONTEXT.md# 测试状态echo"## 测试状态">> CONTEXT.mdif pytest tests/ -q--tb=no 2>/dev/null;thenecho"- 测试结果: ✅ 全部通过">> CONTEXT.mdelseecho"- 测试结果: ❌ 有失败的测试">> CONTEXT.mdfiecho"">> CONTEXT.md# Python 环境echo"## 环境信息">> CONTEXT.mdecho"- Python 版本: $(python --version2>&1)">> CONTEXT.mdecho"- 已安装包:">> CONTEXT.mdpip list 2>/dev/null |head-10|sed's/^/ - /'>> CONTEXT.md在 CLAUDE.md 中添加：
## 动态上下文在执行任何任务前，先运行 `scripts/generate_context.sh` 生成最新的 CONTEXT.md，然后读取它了解项目当前状态。好处：AI 能感知 Git 分支、修改文件、测试状态等动态信息，做出更准确的决策。
增加 Hook 种类
Pre-commit Hook 增强：添加更智能的检查逻辑
#!/usr/bin/env bash# 检查是否修改了核心文件（如 hot-trends 的 fetchers 目录）CHANGED=$(gitdiff--cached --name-only)ifecho"$CHANGED"|grep-q"src/fetchers/";thenecho"⚠️ 修改了数据抓取器，请确认："echo" 1. 是否需要更新对应的测试？"echo" 2. 是否需要更新 API 文档？"fi# 运行测试pytest tests/ -v# 代码风格检查flake8 src/# 代码格式化检查black --check src/其他可选 Hook：
pre-push
: 推送前运行完整测试套件 commit-msg
: 验证提交信息格式（如约定式提交） post-merge
: 合并后自动安装依赖
实际效果：当你在 hot-trends 中修改 src/fetchers/zhihu.py 时，Hook 会提醒你检查测试和文档。
Level 3 Harness：完整工程化体系
Level 3 是企业级的 Harness，适用于团队协作和大型项目。对于 hot-trends 这样的单人项目，可以根据需要选择性采用。
1. 多层约束
企业级 Harness 层级
|
|
|
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
示例：
-
L1: 公司要求所有项目使用 Python type hints -
L2: 后端团队统一使用 FastAPI + Pydantic -
L3: hot-trends 项目使用特定的目录结构（见 CLAUDE.md） -
L4: fetchers 模块有特殊的安全要求（如 API key 管理）
2. 纵深防御
通过多层验证确保代码质量：
|
|
|
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
原理：每一层都有机会发现问题，越早发现成本越低。
hot-trends 实践：
-
第1层：CLAUDE.md 规定 fetcher 不能混入过滤逻辑 -
第2层：单元测试验证每个模块功能 -
第3层：Hook 在提交前自动运行 lint 和 test -
第4层：GitHub Actions CI 流程（可选） -
第5层：如果是团队项目，可以设置 PR 审查
3. 熵管理流程
建立定期检查机制，防止系统逐渐混乱：
# 每周熵管理 Checklist## 代码质量- [ ] 运行 `flake8 src/` 检查代码风格- [ ] 运行 `pytest tests/ -v` 检查测试通过率- [ ] 检查是否有新的 TODO 注释## 文档同步- [ ] 检查 CLAUDE.md 是否需要更新- [ ] 检查 README 是否过时- [ ] 检查 CHANGELOG 是否遗漏## 依赖管理- [ ] 运行 `pip list --outdated` 检查过期依赖- [ ] 运行 `pip audit` 检查安全漏洞熵增的表现：
-
代码风格不一致（如有的地方用 camelCase，有的用snake_case） -
目录结构混乱（如在 src/根目录直接放文件） -
测试覆盖率下降（新增代码没有测试） -
文档过时（README 中的使用说明与实际不符）
建议：对于 hot-trends 这样的个人项目，可以每月进行一次熵管理检查。
常见问题
Q1：Harness 会不会限制 AI 的创造力？
答案：不会。
Harness 约束的是边界，不是方法。
约束：使用 Python type hintsAI 仍然自由：选择算法、设计模式、实现细节约束：测试覆盖率 > 80%AI 仍然自由：测试怎么写、测什么约束：代码风格统一（PEP 8）AI 仍然自由：逻辑实现方式Q2：CLAUDE.md 写多少合适？
答案：刚好够用。
太少：AI 还是自己猜太多：没人看，变成形式主义刚好：覆盖核心决策点建议：
-
项目概述：50-100字 -
技术栈：列出主要技术 -
目录结构：核心目录即可 -
代码规范：5-10条核心规则 -
质量要求：可量化的指标
Q3：和 Superpowers / OpenSpec 的关系？
OpenSpec → 定义「做什么」（需求约束）Superpowers → 定义「怎么按流程做」（流程约束）Harness → 定义「如何确保可控」（行为约束）三者结合 = 完整的 AI 编程工程化体系
我们会在下一篇「铁三角导论」中详细讲解。
下一步
你已经学会了 Harness Engineering 的基本概念和实践，知道它如何给 AI 套上缰绳。
到此为止，你已经认识了「铁三角」的三个工具：
- Superpowers
→ 流程约束 ✅ - OpenSpec
→ 需求约束 ✅ - Harness Engineering
→ 行为约束 ✅
下一篇，我们来讲 铁三角导论：三层架构设计，揭示三者如何协同工作。
扩展阅读
-
Claude Code 官方文档 -
CLAUDE.md 最佳实践 -
Git Hooks 原理