如何只用自己拥有的文件约束编码智能体

来源:Tessl:产品与工程博客 2026年10月11日 00:00 AIHOT 评分:65 精选
摘要:Tessl 博客文章介绍用四个可拥有的文件杠杆约束编码智能体:CLAUDE.md 指令、.claude/rules/ 路径级规则、.claude/ 下的能力配置和 .claude/hooks/ 钩子。
推荐理由:作者用同一工单三次实测对比 charter 各文件杠杆的效果,方法可迁移到自己的仓库,并指出机器可查与需人审的边界。
# 如何只用自己拥有的文件约束编码智能体 > 原标题:How to constrain a coding agent using only files you own - 来源:Tessl:产品与工程博客 - 发布时间:2026-10-11T16:00:00.000Z - AIHOT:https://aihot.news/items/twhuaks920iaqd2y7frq8bgbw - 原文:https://tessl.io/blog/how-to-constrain-a-coding-agent-using-only-files-you-own ## 摘要 Tessl 博客文章介绍用四个可拥有的文件杠杆约束编码智能体:CLAUDE.md 指令、.claude/rules/ 路径级规则、.claude/ 下的能力配置和 .claude/hooks/ 钩子。 ## 推荐理由 作者用同一工单三次实测对比 charter 各文件杠杆的效果,方法可迁移到自己的仓库,并指出机器可查与需人审的边界。 ## 正文 · 中文译文 我给一个编码代理一张工单,没有给它任何章程。这个仓库像真实项目一样,横跨了三个时代。一个 2026 年的领域层把一切都做对了,而一个 2023 年的上帝文件加上一个没人敢碰的 2021 年冻结模块,数量是它的十倍。 代理从未打开正确的代码。它去了上帝文件,调用 `random.randint` 掷骰子,并在没有种子的情况下序列化总数。它通过一个确实存在且能工作的辅助函数重写了一条日志记录,还两次伸手进了冻结模块。 _得分:_八项检查中通过一项。那个仓库里没有任何东西是坏的,代理只是照抄了摆在它面前的代码。所有本可以拦住它的东西,都是我还没写出来的文件。 ## 你真正拥有的东西 我从事 harness 与章程工程:运行代理的引擎,以及它最先读取的规则。这就是《Harness Engineering》这本书以及我的开源章程框架工具 Keystone 的主题。11 月我将在 AIDevCon 主持一场九十分钟的工作坊,让一屋子工程师编写这些文件,并衡量每一个文件带来了什么。 写一个 `CLAUDE.md` 的建议现在到处都是,这是好建议,但那个文件只是四个杠杆之一。另外三个就在同一个仓库里、在你已经拥有的路径下,而许多团队并没有交付足够多的它们。 章程的哪一部分在代理不同意它时仍然成立,每一部分又买到了什么?这两个问题都能在一台笔记本电脑上回答,下面就是我在同一张工单上回答三次所得到的结果。 ## 你的章程是四个杠杆,不是一个文件 传统版本:把你的标准写进 `CLAUDE.md`。 每个人都会写那个杠杆,而另外三个就在它旁边。四个都是文件,四个都属于你,四个都位于代理在写下一行代码之前会读取的路径下: 1. **指令**是 `CLAUDE.md`。这个仓库现在是什么,用现在时描述。 2. **约束**是 `.claude/rules/`,按路径限定范围,每条规则都带有导致它的那次事故的日期。 3. **能力**是 `.claude/commands/`、`.claude/skills/`、`.claude/agents/`、`.claude/settings.json` 和 `.mcp.json`。代理能够伸手拿到什么,以及被允许运行什么。 4. **检查**是 `.claude/hooks/`。什么会拒绝它。 _左边的三个杠杆改变代理读取和伸手去拿的东西。右边那个是唯一能够拒绝的。_ 能力杠杆是通常没有被设计的那一半。它上面有四级台阶:一条命令、一项技能、一个子代理、一个 MCP 服务器。家族测试可以对它们进行分类。移除那个东西,如果代理能做的事变少了,那它就是一种能力。如果代理做同样的工作、只是做得更差,那你写了一条规则,并把它打扮成了技能。 授权列表也属于那个杠杆,而且它是对你本意的有损翻译。一个指向 `make` 目标的允许列表,与一个指向命令字符串的允许列表,所表达的东西是不同的。 **这对你意味着什么:**在你自己的仓库上运行 `ls -R .claude/`。如果答案只是一个设置文件、别无其他,那你就拥有四个杠杆,却只交付了一个。 ## 两个杠杆说服。一个拒绝。 指令会被读取。按路径限定的规则会被读取。任何被读取的东西都可以被争辩,而代理会说服自己放弃一条被周围代码所否定的规则。能力杠杆不争辩任何一方,因为它改变的是代理能够伸手拿到什么,而不是它相信什么。 钩子不会被读取。它是一个在回合内运行并返回拒绝的谓词。你无法与它谈判。 四十行 Python 挂在这个差异的两端。一个是 `PreToolUse` 钩子,用来阻止写入;另一个是 `make gate`,也就是 CI 运行的东西。一个谓词,两个挂载点,没有重复的逻辑。这种形态正是它能传播的原因。 那些有说服力的杠杆仍然能买到很多东西,但有一个条件:规则必须与某些东西相悖。你的代码库已经遵循的规则不约束任何东西。智能体会通过模仿得到同样的答案,所以你无法分辨是哪一个让你到达那里。 所以要把规则写在规则与代码相悖的地方。在工作坊仓库中,一个模块从会话中推导请求权限,另一个模块直接从请求体中读取它。两种模式都活着,两种都能用,所以章程必须做出选择。它的职责是说明该复制这两个真实模式中的哪一个,而这就是大多数改造的情况。 同一张工单跑了三次。裸跑改了 3 个文件,加了 49 行,8 项中通过 1 项。带章程的跑改了 3 个文件,加了 102 行,8 项中通过 8 项。更大的差异反而是更好的那个,这一点值得在有人开始为改动行数做优化之前大声说出来。 **这对你意味着什么:**你最不愿看到被打破的那条规则,应该放在那个_拒绝_的杠杆上。 ## 你的所有权止于何处 一个程序可以解决九项检查中的八项。差异是否留在范围内?每个随机种子是否都已设定?日志是追加而不是重写?还有五项问的是这类问题,脚本对每一项都能不带主观判断地作答。 第九项是 `authority.semantic`,它问的是访问检查_对这个功能_是否正确。没有谓词能解决这个问题,所以评分器打印一个问号然后等待。 _两种判定读的是同一个差异。只有钩子能在写入发生之前阻止它。只有审查者能解决第九项检查。_ 在八项全过的那次运行中,一个审查者子智能体读了差异并填上了第九列: - 处理程序以 `session.is_dungeon_master()` 为门控,所以它会拒绝一个请求保存自己角色的玩家。验收标准 4 允许这样做。 - 谁魅惑了一个战斗者,谁就在持续时间内控制他。处理程序没有考虑这一点,工单对此也只字未提,所以智能体本应提出这个问题,而不是自己挑一个答案。 - 测试通过一个模块全局变量来设置它的请求,所以它只走了拒绝路径。 八项绿色检查。三个真实缺陷,其中一个是权限 bug。 绿色的记分卡不等于正确的改动。它只是一个没有机械可检测问题的改动,而这个距离正是你的审查注意力该放的地方。 ## 这在软件生命周期中的位置 章程是约束中你完全拥有的那部分。它住在仓库里,受版本控制,随克隆一起到达。四个文件在每一台检出代码的机器上改变智能体的行为。 我见过的许多 harness 和工厂图里都有一个标着质量门的方框,而那个方框掩盖了这个问题:_你的哪些标准根本能当门_?在一个仓库的一张工单上,我得到八和一,但我选的规则就是为了让效果可见,所以把这个比例当作演示。你的会不一样。 方向是我会据此规划的东西。随着智能体写更多的代码,通过那道门的量会攀升,而不可判定那一列并不会随之缩小。所以当一条规则超出了章程,就说出它上面那一级然后停下,因为一个 markdown 文件装不下智能体能够到并删除的东西。 规则不是静态的。它们有生命周期,会从部落知识走向章程,走向约束框架,再走向工厂。_具体在哪一步_取决于所关注的问题。 ## tl;dr 拿一张工单。在完全没有章程的情况下,把它跑在你的代码库上,然后用你事先写好的检查项给结果打分。那次运行就是事故本身,你之后写的每一条规则都应该指向它。然后一次加一个杠杆,重新运行同一张工单,并指出哪个杠杆改变了哪个检查项。 你会发现两件事。你的一些规则其实什么都没约束,因为代码本来就符合它们。而至少有一条你在意的规则,没有任何机器能检查,这反而让它值得占用一个人的时间。 **要点:**约束编码智能体的每一条限制,都是你拥有的一个文件。唯一的问题是,其中哪些你费心写了下来。 ## 正文 · 原文 I gave a coding agent one ticket and no charter. The repository was three eras deep, the way a real one is. A 2026 domain layer does everything correctly, and a 2023 god file plus a frozen 2021 module nobody is allowed to touch outnumber it ten to one. The agent never opened the correct code. It went to the god file, called `random.randint` for a dice roll, and serialized the total with no seed. It rewrote a log entry through a helper that exists and works, and it reached into the frozen module twice. _Score:_ one check out of eight. Nothing in that repository was broken, and the agent copied the code in front of it. Everything that would have stopped it was a file I had not written yet. ## What you actually own I work on harness and charter engineering: the engine that runs an agent, and the rules it reads first. That is the subject of _Harness Engineering_, the book, and of Keystone, my open source charter framework tool. In November I’m running a ninety-minute workshop at AIDevCon where a room of engineers writes those files and measures what each one bought. The advice to write a `CLAUDE.md` is everywhere now, and it is good advice, but that file is one lever of four. The other three sit beside it in the same repository, under paths you already own, and many teams don’t ship enough of them. Which part of a charter holds when the agent disagrees with it, and what does each part buy? Both are answerable on a laptop, and below is what I got answering them three times on one ticket. ## Your charter is four levers, not one file The conventional version: write your standards down in `CLAUDE.md`. Everyone writes that lever, and three more sit next to it. All four are files, all four are yours, and all four live under paths the agent reads before it writes a line: 1. **Instruction** is `CLAUDE.md`. What this repository is, in the present tense. 2. **Constraint** is `.claude/rules/`, path-scoped, each rule carrying the date of the incident that caused it. 3. **Capability** is `.claude/commands/`, `.claude/skills/`, `.claude/agents/`, `.claude/settings.json` and `.mcp.json`. What the agent can reach for, and what it is allowed to run. 4. **Check** is `.claude/hooks/`. What refuses it. _The three levers on the left change what the agent reads and reaches for. The one on the right is the only one that can refuse._ The capability lever is the half that is not usually designed. Four rungs sit on it: a command, a skill, a sub-agent, an MCP server. The family test sorts them. Remove the thing, and if the agent can do less, it was a capability. If the agent does the same work and just does it worse, you wrote a rule and dressed it as a skill. The grant list belongs on that lever too, and it is a lossy translation of what you meant. An allowlist pointing at `make` targets says something different from one pointing at command strings. **What this means for you:** run `ls -R .claude/` on your own repo. If the answer is a settings file and nothing else, you own four levers and ship one. ## Two levers persuade. One refuses. Instructions get read. Path-scoped rules get read. Anything read can be argued with, and an agent will talk itself out of a rule the surrounding code contradicts. The capability lever does not argue either way, because it changes what the agent can reach rather than what it believes. A hook is not read. It is a predicate that runs inside the turn and returns a refusal. You cannot negotiate with it. Forty lines of Python mount at both ends of that difference. One is a `PreToolUse` hook that stops the write, and the other is `make gate`, which is what CI runs. One predicate, two mounting points, and no duplicated logic. That shape is why it travels. The levers that persuade still buy a great deal, on one condition: the rule has to disagree with something. A rule your codebase already follows constrains nothing. The agent would have imitated its way to the same answer, so you cannot tell which one got you there. So write the rule where rule and code disagree. In the workshop repo, one module derives request authority from the session, and another reads it straight out of the request body. Both patterns are live and both work, so the charter has to pick. Its job is to say which of the two real ones to copy, and that is most retrofits. Three runs of the same ticket. The bare run changed 3 files, added 49 lines, and passed 1 of 8. The chartered run changed 3 files, added 102 lines, and passed 8 of 8. The bigger diff was the better one, which is worth saying out loud before somebody starts optimizing for lines changed. **What this means for you:** the rule you would be most upset to see broken belongs on the lever that _refuses_. ## Where your ownership stops A program can settle eight of the nine checks. Did the diff stay in scope? Was every roll seeded? Was the log appended rather than rewritten? Five more ask questions of that shape, and a script answers each without an opinion. The ninth is `authority.semantic`, and it asks whether the access check is right _for this feature_. No predicate settles that, so the scorer prints a question mark and waits. _Both verdicts read the same diff. Only the hook stops a write before it exists. Only the reviewer settles the ninth check._ On the run that passed all eight, a reviewer sub-agent read the diff and filled in that ninth column: - The handler gates on `session.is_dungeon_master()`, so it refuses a player asking for a save on their own character. Acceptance criterion 4 allows it. - Whoever charmed a combatant controls them for the duration. The handler does not consider that, and the ticket is silent on it, so the agent should have raised the question rather than picking an answer. - The test sets up its request through a module global, so it exercises only the refusal path. Eight green checks. Three real defects, and one of them a permissions bug. A green scorecard is not a correct change. It is a change with no mechanically detectable problem, and that distance is where your review attention belongs. ## Where this sits in the software lifecycle The charter is the part of the constraints that you own outright. It lives in the repo, gets version controlled, and arrives with a clone. Four files change agent behavior on every machine that checks the code out. Many harness and factory diagrams I have seen has a box labeled quality gate, and that box hides the question: _which of your standards can be a gate at all_? On one ticket in one repository I get eight and one, but I chose rules designed to make the effect visible, so treat that ratio as a demonstration. Yours will be different. Direction is what I would plan around. As agents write more of the code, the volume past that gate climbs, and the undecidable column does not shrink with it. So when a rule outgrows the charter, name the rung above it and stop, because a markdown file cannot hold what the agent can reach and delete. Rules are not static. They have a lifecycle and they move from tribal knowledge to the charter to the harness to the factory. _Where_ depends on the concern. ## tl;dr Take one ticket. Run it against your repo with no charter at all, and score the result against checks you wrote beforehand. That run is the incident, and every rule you write afterward should point back at it. Then add the levers one at a time, re-running the same ticket, and name which lever moved which check. You will find two things. A few of your rules constrain nothing, because the code already agreed with them. And no machine can check at least one rule you care about, which makes it the one worth a human’s time. **The takeaway:** every constraint that binds a coding agent is a file you own. The only question is which of them you have bothered to write.