大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



理论再漂亮，落不到项目结构里，都是纸上谈兵。

上周发完《Harness Engineering 实战》，有读者留言： “文中提到的各种层，到底写在哪里？”

非常好的问题，这个是理论到工程落地的问题，这些“层”，需要落地到具体项目的对应结构中。

AI 编程的可靠性，从来不是靠“在对话框里多嘱咐两句”。 是靠工程结构硬约束。

这篇文章直接给一个最小可运行 Demo，供大家参考和一起交流提高。

---

一个标准的 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/                 # 单元测试 & 边界用例 

别嫌多。 每一层，都在替你挡一个线上故障。

---

放哪： 项目根目录。 

作用： 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+` 异步语法。 

放哪： 项目根目录。 

作用： 开发者 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/ 目录。 

作用： 限制 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/。 

作用： 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 按钮就是灰色的，谁的面子也不给。

---

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 的核心逻辑不变，只是注入方式不同。

---

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 代码进不了仓库。

---

坑 1：AI 绕过 pre-commit 

有些开发者用 git commit –no-verify 强行提交。 

解法： 在 GitHub Actions 里加 required: true 分支保护。CI 不绿，PR 按钮是灰的。

坑 2：AGENTS.md 写太长 

AI 对超过 50 行的 System Prompt 注意力会衰减。 

解法： 只写“红线”与“输出格式”。具体实现逻辑，交给代码审查。

---

AI 不是魔法。 

你给它的边界越清晰，它给你的惊喜就越大。

别指望一句“帮我写个系统”就能搞定一切。 

把约束写进文件，把校验交给流水线，把合并权握在自己手里。

这才是 2026 年开发者的生存底线。

---

🍵 延伸交流 

本文完整 Demo 工程（含 AGENTS.md 模板、pre-commit 配置、CI 脚本与 check_ai_code.py 校验器）已上传。

关注公众号，后台回复 harness-demo 自动获取 Gitee 仓库链接。

想交流 AI 相关想法和内容，可扫码进技术交流群。 

群里不卷 KPI，只聊 AI 新玩法、提效工具和偶尔的“合法发呆”。

注：微信群有有效期，假如失效或者满200人，请关注公众号添加微信拉入群。

---

关于作者

作者：近 20 年技术生涯，待过大厂也创过业。 懂大厂的规范与困境，也懂创业公司的敏捷与无奈。 懂技术也懂商业，实践用技术重构传统业务。公众号「AI 提效随笔」主理人。

欢迎转发，转载请注明出处。

---

📌 觉得有用？欢迎：

点赞 - 让更多人看到

转发 - 分享给需要的同事/朋友

关注 - 不错过后续更多精彩内容分享