理论再漂亮，落不到项目结构里，都是纸上谈兵。
上周发完《Harness Engineering 实战》，有读者留言： “文中提到的各种层，到底写在哪里？”
非常好的问题，这个是理论到工程落地的问题，这些“层”，需要落地到具体项目的对应结构中。
AI 编程的可靠性，从来不是靠“在对话框里多嘱咐两句”。 是靠工程结构硬约束。
这篇文章直接给一个最小可运行 Demo，供大家参考和一起交流提高。
01
先看目录结构
一个标准的 AI Harness 工程，长这样：
harness-demo/
├── AGENTS.md # 约束层：AI 的行为准则与边界
├── .pre-commit-config.yaml # 校验层：提交前自动拦截
├── config/
│ └── harness.yaml # 执行层：工具权限/超时/沙盒配置
├── .github/
│ └── workflows/
│ └── ai-check.yml # 监控层：CI 流水线强制校验
├── scripts/
│ └── check_ai_code.py # 自定义校验脚本
├── src/ # 你的业务代码
└── tests/ # 单元测试 & 边界用例
别嫌多。 每一层，都在替你挡一个线上故障。
02
让我们来逐层拆解
层一：约束层（AGENTS.md）
放哪： 项目根目录。
作用： AI 启动时自动读取，定义“能做什么/不能做什么”。
# AGENTS.md
## Context
你正在开发一个用户注册服务 (`src/user_service.py`)。
## Security Constraints (红线)
1. **密码安全**：绝对禁止明文存储！必须使用 `bcrypt` 或 `argon2` 哈希。
2. **输入校验**：邮箱必须符合 RFC 5322，禁止使用简单的 `if '@' in email`。
3. **防注入**：禁止字符串拼接 SQL。必须使用 ORM 或参数化查询。
4. **错误处理**：注册失败时，禁止在异常信息中泄露用户是否存在（防枚举攻击）。
## Tools
优先使用 `pydantic` 校验，`SQLAlchemy 2.0+` 异步语法。
层二：校验层（.pre-commit-config.yaml）
放哪： 项目根目录。
作用： 开发者 git commit 时，自动跑 Lint 与自定义脚本，拦截 AI 幻觉代码。
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.4.5
hooks:
- id: ruff
args: [--fix, --exit-non-zero-on-fix]
- id: ruff-format
- repo: local
hooks:
- id: ai-harness-check
name: AI 代码安全校验
entry: python scripts/check_ai_code.py
language: system
types: [python]
💡 原理与运行机制：这是 Git 的“安检门”。pre-commit 会在你敲下 git commit 的瞬间拦截操作，依次运行列表里的脚本。
💡怎么跑：只要执行过 pre-commit install，它就会自动挂载到 .git/hooks/。
💡为什么这么配：ruff 负责秒级格式化；local 钩子调用自定义脚本。若脚本检测到违规（返回 exit code 1），提交直接中止，烂代码进不了仓库。
层三：执行层（config/harness.yaml）
放哪： config/ 目录。
作用： 限制 AI Agent 能调用的 CLI、文件读写白名单、超时阈值。
agent:
sandbox:
enabled: true
allowed_paths:
- ./src
- ./tests
- ./logs
blocked_commands:
- rm -rf
- sudo
- curl -O
limits:
max_tokens_per_request: 8192
timeout_seconds: 30
max_file_edits_per_session: 15
💡 原理与运行机制：这是 AI Agent 的“紧箍咒”。不同于给人看的文档，这个文件是给 AI 框架（如 OpenClaw, LangChain, 或 IDE 的 Agent 模式）读取的配置。
💡 怎么跑：Agent 启动时会自动加载 config/ 下的 YAML，将其转化为运行时的沙盒策略。
💡 为什么这么配：allowed_paths 限制 AI 只能在项目目录读写，防止误删系统文件；blocked_commands 禁止高危指令；limits 防止 AI 陷入死循环刷爆 Token 账单。
层四：监控层（.github/workflows/ai-check.yml）
放哪： .github/workflows/。
作用： PR 合并前，CI 强制跑完整测试与覆盖率。不达标，不准合入。
name: AI Harness Check
on: [pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with: { python-version: '3.11' }
- name: Install deps
run: pip install -r requirements.txt
- name: Run Lint
run: ruff check src/
- name: Run Tests
run: pytest tests/ --cov=src --cov-fail-under=80
💡 原理与运行机制：这是云端“终审法庭”。本地检查可能被 git commit --no-verify 绕过，但 GitHub Actions 是服务器端的强制拦截。
💡 怎么跑：当你发起 Pull Request 时，GitHub 会自动启动虚拟服务器（Runner），按脚本拉代码、装环境、跑测试。
💡 为什么这么配：on: [pull_request] 确保只在合并前触发；--cov-fail-under=80 强制要求测试覆盖率。只要有一项标红，PR 的 Merge 按钮就是灰色的，谁的面子也不给。
03
Q&A：AI 为什么会乖乖读 AGENTS.md？CLI 怎么用？
Q1：需要装插件或写代码加载吗？
A：不需要。 这是 2026 年 AI IDE（Cursor/Trae/Qoder/Claude Code）的原生标准。 打开项目时，IDE 会自动扫描根目录的 AGENTS.md，并将其静默注入到 System Prompt 中。 你不需要任何配置。只要文件在，AI 写代码前就已经“背熟”了你的红线。
Q2：如果不用 IDE，直接用 CLI（如终端交互/通用 API）呢？
A：主流 AI CLI（如 Anthropic 官方 claude）已支持自动读取；但通用终端或旧版 CLI 默认不会读。
你需要手动注入。提供两种解法：
解法 1：一键注入脚本（推荐）
在项目根目录建 run.sh，自动把 AGENTS.md 拼成 System Prompt：
#!/bin/bash
# 读取约束文件
SYSTEM_PROMPT=$(cat AGENTS.md)
# 调用你的 CLI 工具（以 claude 为例）
claude --system "$SYSTEM_PROMPT" "$@"
运行：./run.sh "帮我写用户注册接口"
解法 2：手动拼接 Prompt
System: 你是一个严格遵守项目规范的工程师。请严格遵循以下约束：
[粘贴 AGENTS.md 全文]
User: 帮我写用户注册接口。
结论： IDE 是“自动挡”，CLI 是“手动挡”。Harness 的核心逻辑不变，只是注入方式不同。
04
怎么跑起来？（3 步）
1.初始化环境
pip install -r requirements.txt
pre-commit install
2.让 AI 生成代码
正常用Cursor/Trae/Qoder 或 CLI 写业务。AI 会自动读取 AGENTS.md 约束，输出符合规范的 src/user_service.py。
3.提交拦截
git add .
git commit -m "feat: add user registration"
# 若违反约束（如明文存密码），pre-commit 直接阻断，AI 代码进不了仓库。
05
实测踩过的 2 个坑
坑 1：AI 绕过 pre-commit
有些开发者用 git commit --no-verify 强行提交。
解法： 在 GitHub Actions 里加 required: true 分支保护。CI 不绿，PR 按钮是灰的。
坑 2：AGENTS.md 写太长
AI 对超过 50 行的 System Prompt 注意力会衰减。
解法： 只写“红线”与“输出格式”。具体实现逻辑，交给代码审查。
06
AI 不是魔法。
你给它的边界越清晰，它给你的惊喜就越大。
别指望一句“帮我写个系统”就能搞定一切。
把约束写进文件，把校验交给流水线，把合并权握在自己手里。
这才是 2026 年开发者的生存底线。
🍵 延伸交流
本文完整 Demo 工程（含 `AGENTS.md` 模板、`pre-commit` 配置、CI 脚本与 `check_ai_code.py` 校验器）已上传。
关注公众号，后台回复 `harness-demo` 自动获取 Gitee 仓库链接。
想交流 AI 相关想法和内容，可扫码进技术交流群。
群里不卷 KPI，只聊 AI 新玩法、提效工具和偶尔的“合法发呆”。
注：微信群有有效期，假如失效或者满200人，请关注公众号添加微信拉入群。
关于作者
作者：近 20 年技术生涯，待过大厂也创过业。 懂大厂的规范与困境，也懂创业公司的敏捷与无奈。 懂技术也懂商业，实践用技术重构传统业务。公众号「AI 提效随笔」主理人。
欢迎转发，转载请注明出处。
📌 觉得有用？欢迎：
点赞 - 让更多人看到
转发 - 分享给需要的同事/朋友
关注 - 不错过后续更多精彩内容分享
