7.4
Roll out and govern a harness落地與治理落地与治理
This chapter assumes you have read Guard the files that hold the rules, Instructions and skills and Record what happened, not what the agent said.
讀這一章,你需要讀過 保護規則本身的檔案、指令與 skill:只載入需要的 和 記下發生了什麼,不是 agent 說了什麼。
读这一章之前,需要先读过保护规则本身的文件、指令与 skill:只加载需要的和记下发生了什么,而不是 agent 说了什么。
The Knowledge經驗分享经验分享
In one sentence
Rolling an agent setup out to a team is mostly a question of who owns the rules and who reviews changes to them. Widen it only when the logs show the rules hold.
一句話
把 agent 設定推給一個團隊,主要是問:誰擁有規則,誰審查對規則的改動。只有紀錄顯示規則撐得住的時候,才擴大範圍。
一句话
把一套 agent 配置推广到团队,主要是两个问题:规则归谁管,谁来审查对规则的改动。只有日志显示规则站得住,才往外放开。
For leaders
- The decision: name an owner for each layer of rules, require a second reviewer for any change to them, and agree what has to be true before the setup goes to the next team.
- The risk: without owners, the rules drift into one copy per person and stale rules stay. I have no team data, so I cannot put a number on it. The chapter gives the design I would use, not a measured result.
- The cost of doing it right: mostly people's time: owners for the core and each area, and a reviewer's time on every rule change. The setup itself adds little.
- Ask the team: "Who owns this rule, who reviewed the last change to it, and what would the logs show if it were wrong?"
給主管
- 要做的決定:為每一層規則指定一個負責人,要求任何改動都有第二位審查者,並先講好:要符合什麼條件,設定才能交給下一個團隊。
- 風險:沒有負責人,規則會漂成每人一份,過期的規則會留著。我沒有團隊的數據,所以給不出數字。這一章給的是我會用的設計,不是量過的結果。
- 做對的成本:主要是人的時間:核心和每個領域的負責人,以及審查者在每次改規則時花的時間。設定本身加的很少。
- 可以問團隊:「這條規則誰負責,上一次改它是誰審查的?如果它是錯的,紀錄會顯示什麼?」
写给管理者
- 要拍板的事:给每一层规则指定负责人,要求对规则的任何改动都有第二个人审查,并约定配置推给下一个团队之前必须满足什么条件。
- 风险:没有负责人,规则会漂移成每人一份,过期的规则也留在那里。我没有团队的数据,所以给不出数字。这一章讲的是我会采用的设计,不是量出来的结果。
- 做对的代价:主要是人的时间:核心层和每个领域的负责人,以及审查者在每次规则改动上花的时间。配置本身增加的很少。
- 可以问团队:“这条规则归谁管?上一次改动是谁审查的?如果它是错的,日志会显示什么?”
The problem
A setup that suits one person has one owner by accident: that person. They write the rules, they notice when a rule is wrong, and they know why each one is there. Hand the same files to ten colleagues and three things go wrong, none of them about the tools.
- Copies drift. Everyone fixes the rules for their own task, in their own copy. After a month there are ten versions, and no one can say which one is "the rules".
- Nobody owns a rule. A rule that was right last year is now wrong, and everyone has learned to ignore it. Rules go stale unless someone is paid in attention to prune them.
- A change breaks someone else. Tightening a rule for one project blocks another team's normal work. The person who made the change never sees the damage.
A fourth worry is a leader's: after the rollout, how do you know what the agents did? That needs a record that someone looks at.
I should be honest about my own position. I built my setup for one person and I have not run a team rollout with measurements. What follows is the design I would use, built from what the setup already does (the parts I can point to), and from the questions I ask before adding anything. Where something is only a proposal, I say so.
問題
適合一個人的設定,只是碰巧有一個負責人:那個人。他寫規則,規則錯了他會發現,每一條為什麼在那裡他也知道。把同樣的檔案交給十個同事,會出三個問題,沒有一個和工具有關。
- 副本會漂移。每個人為自己的任務,在自己的副本裡修規則。一個月後有十個版本,沒有人說得清哪一個是「規則」。
- 沒有人負責一條規則。去年還對的規則,現在錯了,每個人都學會了不理它。規則會過期,除非有人用心力去修剪它。
- 一個改動弄壞別人的事。為一個專案收緊一條規則,擋住了另一個團隊的正常工作。做改動的人,永遠看不到傷害。
第四個擔心是主管的:推出去之後,你怎麼知道 agent 做了什麼?這需要一份有人在看的紀錄。
我該老實說我自己的位置。我的設定是為一個人建的,我沒有帶著量測做過團隊推行。下面是我會用的設計,建在設定現在已經做到的事上(我能指出來的部分),以及我加任何東西之前問的問題上。只是提議的地方,我會說明。
问题
适合一个人的配置,只有一个负责人,而且是碰巧的:就是他自己。规则他来写,规则错了他会发现,每条为什么在那里他都清楚。把同样的文件交给十个同事,会出三个问题,都和工具无关。
- 副本会漂移。每个人都为自己的任务,在自己的副本里改规则。一个月后有十个版本,没人说得清哪一个是“规则”。
- 没人负责某条规则。去年还对的规则,现在错了,大家都学会了无视它。除非有人专门花精力去修剪,否则规则会过期。
- 一次改动弄坏别人。为一个项目收紧一条规则,会挡住另一个团队的正常工作。做改动的人永远看不到这些破坏。
还有第四个担心,是管理者的:推广之后,你怎么知道 agent 做了什么?这需要一份有人会去看的记录。
我要说清楚自己的位置。我的配置是为一个人搭的,我没有带着测量去做过团队落地。下面讲的,是我会采用的设计,它根据这套配置现在能做的事(我能指出来的那些部分)和我在加任何东西之前问的那些问题搭出来。只是建议的地方,我会说明。
How it works
Who owns the rules
The question "who owns the rules" has no single answer, because not all rules are alike. I split them into three layers, by who is hurt when one is wrong.
- The core. The short rules every task must follow, and the files that enforce them (the fence from Guard the files that hold the rules). A mistake here reaches everyone. It has one or two named owners, and nobody else edits it.
- The team layer. Domain skills, the team's knowledge base (an index of the code, see A knowledge base: an honest index of the code), and settings that are the same for everyone, such as which paths no agent may touch. Each area has one owner: the person who knows that part of the code. A skill about deployment belongs to whoever deploys.
- The personal layer. A user name, a language, the folder where your repositories sit on your machine. It belongs to the individual. It is not committed, because it holds paths that exist on one computer only.
Two mechanisms make this workable in my setup, and a team can copy the idea without the tool.
An override is a small config next to the default, not a copy of it. It lists only what you change. A person who wants to add one forbidden path writes one line; they do not fork the whole rule file. So the team's customisation stays a few lines that anyone can read, and an upgrade of the core does not collide with it. In my implementation the core's guardrails cannot be removed by an override: if an override drops them, the engine puts them back and reports an error. The setup's health check also lists what every override changes, which gives a reviewer one place to look.
One rule has one main source. The same rule written in three files is how copies drift (Instructions and skills). When you assign owners, assign them to sources. A rule with two homes has two owners, which means none.
Who reviews a change to a rule
A rule file is not documentation. It is what the agent obeys, so changing it changes what the team's agents do tomorrow. I treat it like code, with four habits.
- The agent does not edit the rules. The files are fenced. A person opens the fence for one session, makes the change, closes it, and reads the diff in git afterwards (Guard the files that hold the rules). That leaves a diff that someone else can review.
- The author is not the only reviewer. The owner of the layer reads the change, and so does someone who was not in the discussion. Treat a rule change like a change to code that an attacker would love to make: a careless or hostile pull request, or a shared skill or knowledge-base file that carries instructions the agent will read as its own, is a way in (Text the agent reads can give it orders). Agree who may approve exceptions, and who takes over a layer when its owner leaves. A rule that makes sense only to its author is a poor rule for an agent too: it will read it cold.
- The review asks six questions. They are the ones I ask before adding anything to my own setup.
- What failure does this prevent? Is there a real example, log or measurement?
- Does the platform already do it? Did anyone read its current docs?
- What does it cost, in context, tokens and time?
- Is it a request in words, or a rule in code (A rule in a prompt is a request)? Is that the right one for the harm?
- When can it be deleted? What would have to change?
- If we moved to another tool, would what we learned still be useful?
- A claim of "this helps" needs the same tasks before and after. If the change is meant to improve results, the review should ask for a before-and-after on fixed tasks (Fixed tasks, scored by a script), not an opinion.
One more rule helps the review. Write down only what the model gets wrong. A line the model would follow anyway costs context and gives a reviewer more to read. If you cannot name an error it prevents, leave it out.
Audit: what the setup leaves behind
A leader who was not there needs to answer "what did the agents do, and who let them?". That is an audit. It works only if the setup writes records that the agent does not control, so here is what mine writes. The first five are built; the last two are ideas.
- One log line per tool call. The kind of call, whether it was let through or refused, which rule refused it, and how long it took. No arguments and no prompt text, except that a refused call keeps its path and command (Record what happened, not what the agent said).
- Refusals, and a count of them. A statistics command sums the prompts, the calls and the refusals, and which part of the setup refused.
- Approvals. Each task's approvals are kept as records that only a person can create, and the task's report shows the time of both.
- The task report. Written by code when a task closes: what was asked, what changed, how many checks and the verdict of each, and what was refused (A report a person can read in five minutes).
- Changes to the rules. The agent cannot edit the rule files. A person does it in a session where every logged call is marked as admin, and the change is a diff in git.
- Idea, not built: who approved. The approval records carry a time. I have not checked whether they carry a person's name, and my setup has one user, so I never needed it. A team does.
- Idea, not built: one place for the logs. In my setup the logs stay on each computer and are not put into git. I have not built any way to gather them across a team.
Who looks, and how often? In my own setup I read the log when a run fails and when I change a rule, not every day (Record what happened, not what the agent said). For a team I would add a short routine, as a proposal: the owner of each layer looks at the refusal counts now and then, and reads the diff of every rule change. A log that nobody owns is not an audit trail.
A rollout in stages
Going wide first and adding review later is how you get ten copies. So I would widen in stages, and I would write down, for each stage, what has to be true before entering it.
- One team, core only. Pick a team that wants the setup and owns its own code. Give the core to one or two owners from day one. Enter when: the team asks for it. Nothing needs to be proven yet.
- Add the team layer. Domain skills, shared settings and the knowledge base come after the team has used the core long enough to know what it needs. Enter when: the core has named owners, and the owner can say what happened in a recent task from the records, not from the agent's summary.
- Open it to the next team. Enter when: the review habit works in the first team. Every rule change had a second reviewer, the diff was read, and any change meant to improve results came with a before-and-after on fixed tasks.
- Everyone, including the colleague who did not ask for it. Enter when: the logs show the rules hold. The signals are in the next section.
These conditions are my proposal. I have not run them on a team, and the thresholds (how long is "long enough") are for you to set.
How you would know it is working
I have no numbers from a team, so this is what I would watch, not what I measured:
- Do people open tasks, or go around the setup? Counts of tasks opened, against work done in plain chats.
- What do the rules refuse, and is it the same thing every week? A rule that refuses the same normal work is a rule to fix (Ask or refuse).
- How often does work come back after approval? Rework after a yes means the gate was read too fast.
- How many local overrides exist, and do they match? See the fork trap below.
Stage 4 asks that these have stopped moving: the refusals are steady and mostly the ones you meant, rework is low, and the overrides are few. "The logs show the rules hold" means that, and nothing grander.
How strong the evidence in this book is
Read the rest of the book with these limits in mind.
- One platform. Everything was built and tried on VS Code Copilot. Other tools have counterparts, but I have not tested them.
- One person's harness. I built it and I use it. Nobody else has tested it, and I am not a neutral judge of it.
- No team data and no incidents. I have not measured adoption, and I have no record of a rule failing in a team. My one measured comparison is four tasks, one run each (Use subagents sparingly).
- Numbers carry their conditions. Where a chapter gives a figure, it gives the run count and the setup next to it, so you can see how far to trust it.
So use the book for its questions and its design, and not as proof. Take a design from it, state what you expect it to do, and check that on your own tasks (Fixed tasks, scored by a script, One run proves nothing). Your numbers should replace mine.
原理
誰擁有規則
「誰擁有規則」沒有單一的答案,因為規則不都一樣。我把它們分成三層,看一條規則錯了會傷到誰。
- 核心。每個任務都必須遵守的短規則,以及執行它們的檔案(保護規則本身的檔案 裡的圍欄)。這裡錯了,影響所有人。它有一、兩位指名的負責人,其他人不改它。
- 團隊層。領域的 skill、團隊的知識庫(程式碼的索引,見 知識庫:程式碼的誠實索引),以及對所有人都一樣的設定,例如哪些路徑任何 agent 都不能碰。每個領域有一位負責人:懂那一塊程式碼的人。部署的 skill 屬於負責部署的人。
- 個人層。使用者名稱、語言、你的倉庫放在你機器上的哪個資料夾。它屬於個人。它不提交,因為裡面是只存在於一台電腦的路徑。
在我的設定裡,有兩個機制讓這件事做得起來。團隊不用那個工具,也可以拿走這個想法。
override 是放在預設旁邊的一個小設定,不是預設的副本。它只列出你要改的。想多加一個禁止路徑的人,寫一行;他不用分叉整份規則檔。所以團隊的客製化,只是幾行誰都讀得懂的東西,核心升級時也不會和它衝突。在我的實作裡,核心的護欄不能被 override 移除:如果 override 把它們拿掉,引擎會放回去並回報錯誤。設定的健康檢查也會列出每個 override 改了什麼,審查者就有一個地方可以看。
一條規則有一個主要來源。同一條規則寫在三個檔案裡,就是副本漂移的起點(指令與 skill:只載入需要的)。指定負責人的時候,指定給來源。有兩個家的規則有兩個負責人,也就是沒有。
誰審查對規則的改動
規則檔不是文件。它是 agent 服從的東西,所以改它,就是改團隊的 agent 明天會做什麼。我把它當程式碼,有四個習慣。
- agent 不改規則。這些檔案被圍起來。由人為一個會話打開圍欄,做改動,再關上,之後在 git 裡讀 diff(保護規則本身的檔案)。這樣會留下一份別人可以審查的 diff。
- 作者不是唯一的審查者。那一層的負責人讀這個改動,另一位沒參與討論的人也讀。把規則的改動,當成攻擊者很想做的程式碼改動:一個草率或惡意的 pull request,或一個共用的 skill 或知識庫檔案,帶著 agent 會當成自己的指令讀進去的內容,都是入口(agent 讀到的文字可能在指揮它)。講好誰可以批准例外,以及負責人離開時誰接手那一層。只有作者看得懂的規則,對 agent 也是差的規則:它是從零開始讀的。
- 審查要問六個問題。這是我在為自己的設定加任何東西之前問的問題。
- 這防止什麼失敗?有真實的例子、紀錄或量測嗎?
- 平台已經做了嗎?有人讀過它現在的文件嗎?
- 它花多少,在上下文、token 和時間上?
- 它是用文字寫的請求,還是程式碼裡的規則(提示裡的規則只是請求)?對這個傷害來說,選對了嗎?
- 什麼時候可以刪掉?要變成什麼樣?
- 如果我們換到別的工具,學到的東西還有用嗎?
- 說「這有幫助」,需要同樣的任務前後各跑一次。如果這個改動是要改善結果,審查就該要求在固定任務上的前後比較(固定的任務,用腳本打分),不是一個意見。
還有一條規則對審查有幫助。只寫模型會做錯的。模型本來就會照做的一行,花上下文,還讓審查者多讀一行。說不出它防止哪個錯誤,就不要寫。
稽核:設定留下什麼
沒在場的主管,需要回答「agent 做了什麼,誰讓它做的?」這就是稽核。只有設定寫下 agent 控制不了的紀錄,它才行得通,所以下面是我的設定寫下的東西。前五項已經做了;後兩項是想法。
- 每次工具呼叫一行紀錄。呼叫的種類、放行還是拒絕、哪條規則拒絕的,以及花了多久。沒有參數,也沒有 prompt 的文字,只有被拒絕的呼叫會保留路徑和指令(記下發生了什麼,不是 agent 說了什麼)。
- 拒絕,以及它的計數。一個統計指令,加總 prompt、呼叫和拒絕,以及設定的哪個部分拒絕的。
- 批准。每個任務的批准,存成只有人能建立的紀錄,任務的報告會顯示兩道批准的時間。
- 任務報告。任務結束時由程式碼寫出:問了什麼、改了什麼、有多少檢查和每個檢查的結論,以及什麼被拒絕了(一份五分鐘讀得完的報告)。
- 規則的改動。agent 不能改規則檔。由人在一個會話裡改,這個會話裡記下的每個呼叫都標成 admin,而改動是 git 裡的一份 diff。
- 想法,沒做:誰批准的。批准的紀錄帶有時間。它們有沒有帶人名,我沒有確認,而我的設定只有一位使用者,所以我從沒需要過。團隊需要。
- 想法,沒做:紀錄放在同一個地方。在我的設定裡,紀錄留在每台電腦上,不放進 git。我沒有做任何跨團隊收集它們的辦法。
誰來看,多久看一次?在我自己的設定裡,我在一次運行失敗和我改規則的時候讀紀錄,不是每天(記下發生了什麼,不是 agent 說了什麼)。對團隊,我會加一個簡短的例行,當作提議:每一層的負責人,每隔一陣子看一下拒絕的計數,並讀每次規則改動的 diff。沒有人負責的紀錄,不是稽核的軌跡。
分階段推行
先鋪開、之後再補審查,就是得到十份副本的辦法。所以我會分階段擴大,並為每個階段寫下:要符合什麼條件才能進入。
- 一個團隊,只有核心。挑一個想要這套設定、自己擁有程式碼的團隊。從第一天就把核心交給一、兩位負責人。進入條件:團隊要它。現在還不需要證明什麼。
- 加上團隊層。領域的 skill、共用設定和知識庫,在團隊用核心夠久、知道自己需要什麼之後再加。進入條件:核心有指名的負責人,而且負責人能靠紀錄,不是靠 agent 的摘要,說出最近一個任務發生了什麼。
- 開放給下一個團隊。進入條件:審查的習慣在第一個團隊行得通。每次規則改動都有第二位審查者,diff 有人讀,任何要改善結果的改動,都附有固定任務上的前後比較。
- 所有人,包括沒有要求的同事。進入條件:紀錄顯示規則撐得住。訊號在下一節。
這些條件是我的提議。我沒有在團隊上跑過,而門檻(多久才算「夠久」)要你自己定。
你怎麼知道它有效
我沒有團隊的數字,所以這是我會看的,不是我量到的:
- 人們是開任務,還是繞過設定?開了多少任務,對比在一般對話裡做的工作。
- 規則拒絕什麼,每週都是同樣的東西嗎?一條一直拒絕同樣正常工作的規則,是該修的規則(詢問不是限制)。
- 批准之後,多常需要返工?批准後返工,表示那道門被看得太快。
- 本機的 override 有多少,它們一致嗎?見下面的分叉陷阱。
第 4 階段要求這些都不再變動:拒絕的數量穩定,而且多半是你想要它拒絕的,返工少,override 也少。「紀錄顯示規則撐得住」,就是這個意思,沒有更大的意思。
這本書的證據有多強
讀這本書其餘的部分時,請記住這些限制。
- 一個平台。一切都是在 VS Code Copilot 上建立和試的。別的工具有對應的東西,但我沒有測過。
- 一個人的 harness。我建了它,我用它。沒有別人測過,我也不是它的中立評審。
- 沒有團隊數據,也沒有事故。我沒有量過採用情況,也沒有團隊裡規則失敗的紀錄。我唯一量過的比較,是四個任務、各跑一次(慎用子 agent)。
- 數字都附著它的條件。一章給出數字時,旁邊會給運行次數和設定,讓你看出該信多少。
所以請把這本書用在它的問題和設計上,不要當成證明。從裡面拿一個設計,說出你預期它做到什麼,再在你自己的任務上檢查(固定的任務,用腳本打分、一次運行證明不了什麼)。你的數字應該取代我的。
原理
规则归谁管
“规则归谁管”没有唯一的答案,因为规则不都一样。我按“一条规则错了,谁受伤”,把它们分成三层。
- 核心层。每个任务都必须遵守的简短规则,以及执行它们的文件(保护规则本身的文件里的围栏)。这里出错,影响所有人。它有一两个指定的负责人,别人不改。
- 团队层。领域 skill、团队的知识库(代码的索引,见知识库:代码的诚实索引),以及对所有人都一样的设置,比如哪些路径任何 agent 都不许碰。每个领域有一位负责人:最了解那部分代码的人。关于部署的 skill,归负责部署的人。
- 个人层。用户名、语言、你的仓库在你机器上所在的文件夹。它归个人。不提交,因为里面的路径只在一台电脑上有效。
在我的配置里,有两个机制让这件事行得通,团队不用这个工具,也可以照搬思路。
override 是放在默认配置旁边的一小份配置,不是默认配置的副本。它只列出你改的东西。想多禁止一个路径的人,写一行就行,不用把整个规则文件 fork 出去。这样,团队的定制就只有几行,谁都读得懂,核心层升级时也不会和它冲突。在我的实现里,核心层的护栏不能被 override 删掉:如果 override 把它们去掉了,引擎会把它们放回去,并报告一个错误。配置的健康检查还会列出每个 override 改了什么,这样审查者有一个地方可看。
一条规则只有一个主来源。同一条规则写在三个文件里,副本就是这么漂移起来的(指令与 skill:只加载需要的)。分派负责人时,要分派给来源。一条规则有两个家,就有两个负责人,也就等于没有。
谁来审查对规则的改动
规则文件不是文档。它是 agent 要服从的东西,所以改它,就是改团队的 agent 明天会做什么。我像对待代码那样对待它,有四个习惯。
- agent 不改规则。这些文件被围起来了。由人为一次会话打开围栏,做完改动,再关上,之后在 git 里读 diff(保护规则本身的文件)。这样留下一份别人可以审查的 diff。
- 作者不是唯一的审查者。这一层的负责人要读这个改动,另一个没参与讨论的人也要读。把规则改动当作攻击者很想做的代码改动来对待:一个草率或怀有恶意的 pull request,或者一个共享的 skill 或知识库文件里带着 agent 会当成自己的指令来读的话,都是入口(agent 读到的文字可能在指挥它)。要约定谁可以批准例外,负责人离开时谁接手这一层。只有作者自己看得懂的规则,对 agent 来说也是差的规则:它是从零开始读的。
- 审查要问六个问题。这是我往自己的配置里加任何东西之前问的那些。
- 它防止什么故障?有真实的例子、日志或测量吗?
- 平台已经做了吗?有人读过它现在的文档吗?
- 它花多少,在上下文、token 和时间上?
- 它是文字里的请求,还是代码里的规则(提示里的规则只是请求)?对这个危害,选这个对吗?
- 什么时候可以删?要变成什么样?
- 如果我们换了别的工具,学到的东西还有用吗?
- 说“这有帮助”,要用同样的任务做前后对比。如果这个改动是要改善结果,审查应该要一份在固定任务上的前后对比(固定的任务,用脚本打分),不是一个意见。
还有一条规矩对审查有帮助。只写模型会弄错的东西。模型本来就会照做的一行,占上下文,还让审查者多读一行。说不出它防止了什么错误,就别写。
审计:配置留下了什么
没在场的管理者,需要能回答“agent 做了什么,是谁让它们做的”。这就是审计。只有配置写下的记录不归 agent 控制,它才行得通,下面是我的配置写了什么。前五项做了,后两项只是想法。
- 每次工具调用一行日志。调用的类型、是放行还是拒绝、哪条规则拒绝的、花了多长时间。不记参数,也不记 prompt 文本,只有被拒绝的调用会保留它的路径和命令(记下发生了什么,而不是 agent 说了什么)。
- 拒绝,以及拒绝的次数。一条统计命令会汇总 prompt、调用和拒绝的数量,以及是配置的哪个部分拒绝的。
- 审批。每个任务的审批,都保存成只有人才能创建的记录,任务报告会显示两道审批的时间。
- 任务报告。任务关闭时由代码写:要求是什么,改了什么,做了多少次检查、每次的结论,以及拒绝了什么(一份五分钟读得完的报告)。
- 对规则的改动。agent 不能改规则文件。由人在一次会话里改,这次会话里每个记录下来的调用都标成 admin,改动就是 git 里的一份 diff。
- 想法,没做:是谁批准的。审批记录带有时间。它们带不带人名,我没查过,而我的配置只有一个用户,所以从来不需要。团队需要。
- 想法,没做:日志集中放一处。在我的配置里,日志留在每台电脑上,不放进 git。我没有做过把它们在团队范围内收集起来的办法。
谁来看,多久看一次?在我自己的配置里,我在一次运行失败时,以及改规则时读日志,不是每天读(记下发生了什么,而不是 agent 说了什么)。对团队,我会加一个简短的例行动作,作为建议:每一层的负责人时不时看看拒绝的次数,并读每一次规则改动的 diff。没人负责的日志,不是审计线索。
分阶段落地
先铺开、后补审查,就会得到十个副本。所以我会分阶段放开,并且为每个阶段写下进入它之前必须满足什么。
- 一个团队,只用核心层。挑一个想要这套配置、并且拥有自己代码的团队。从第一天起,把核心层交给一两个负责人。*进入条件:*这个团队来要。现在还不需要证明什么。
- 加上团队层。领域 skill、共享设置和知识库,在这个团队用核心层用得足够久、知道自己需要什么之后再加。*进入条件:*核心层有了指定的负责人,而且负责人能根据记录,而不是 agent 的摘要,说出最近一个任务里发生了什么。
- 放给下一个团队。*进入条件:*审查的习惯在第一个团队里行得通。每次规则改动都有第二个审查者,diff 被读过,凡是要改善结果的改动,都附了固定任务上的前后对比。
- 所有人,包括没要求过的那位同事。*进入条件:*日志显示规则站得住。信号在下一节。
这些条件是我的建议。我没有在团队里跑过它们,阈值(多久才算“足够久”)由你来定。
怎么知道它在起作用
我没有来自团队的数字,所以这是我会盯的东西,不是我量过的东西:
- 大家是在开任务,还是绕开这套配置?开了多少任务,对比在普通对话里完成的活。
- 规则拒绝了什么?每周都是同样的东西吗?一条总是拒绝同样的正常工作的规则,是要修的规则(询问不是限制)。
- 批准之后有多少活被打回来?点头之后又返工,说明关卡被读得太快。
- 本地 override 有多少,它们一样吗?见下面的 fork 陷阱。
第 4 阶段要求这些都不再变动:拒绝的次数稳定,而且多半是你想拒绝的那些,返工很少,override 很少。“日志显示规则站得住”指的就是这个,没有更大的含义。
这本书里的证据有多强
读这本书的其余部分,请记住这些局限。
- 一个平台。所有东西都是在 VS Code Copilot 上搭建和试验的。别的工具有对应的东西,但我没有测过。
- 一个人的 harness。我搭的,我在用。没有别人测过,我也不是它的中立评判者。
- 没有团队数据,也没有事故。我没有测过采用情况,也没有规则在团队里失效的记录。我唯一量过的对比是四个任务,各跑一次(慎用子 agent)。
- 数字带着它的条件。章节里给出数字的地方,都在旁边写了运行次数和配置,好让你看出该信到什么程度。
所以,请把这本书当作问题和设计来用,不要当作证明。从中取一个设计,说明你预期它做什么,再在你自己的任务上检验(固定的任务,用脚本打分、一次运行证明不了什么)。你的数字应该取代我的。
Costs and traps
The owner becomes a bottleneck. If every rule change goes through two people, people stop proposing changes and start keeping private copies, which is the problem you were solving. Keep the core small, so that few changes need the strict path, and let the team layer move fast.
Review of rules is unglamorous. No one is thanked for a rule that was not added. Put the owner's time in someone's plan, or the review turns into a rubber stamp.
A reviewer must be able to judge the rule. A rule about a deployment path reviewed by someone who has never deployed is only a spelling check.
Too many local overrides is a fork. If most users carry the same override, it belongs in the team layer. Look at the overrides now and then, and promote the common ones.
Logs hold things about people. A log of every call says when someone worked and what they asked the agent to touch. Decide who may read it and how long it is kept before you collect it centrally.
A stage gate is only as good as the record. A hole in the logs (Record what happened, not what the agent said) makes "the rules hold" look true when it is not known.
I have no team data. The three layers, the review habits, the audit routine and the stages are a design built on one person's use. I have not measured adoption or tracked who edits what in a team. Treat them as a starting point to check, not as results.
代價和陷阱
負責人變成瓶頸。如果每次改規則都要經過兩個人,人們就不再提改動,轉而留私人副本,也就是你本來要解決的問題。核心要小,讓需要嚴格流程的改動很少,團隊層則讓它走得快。
審查規則不風光。沒有人會因為一條沒加的規則被感謝。把負責人的時間排進某個人的計劃,不然審查會變成蓋章。
審查者必須能判斷這條規則。一條關於部署路徑的規則,讓從沒部署過的人審查,只是拼字檢查。
太多本機 override,就是分叉。如果多數使用者都帶著同一個 override,它就屬於團隊層。時不時看一下 override,把常見的升上去。
紀錄裡有關於人的事。一份每個呼叫的紀錄,會說某人什麼時候工作,以及他要 agent 碰什麼。在集中收集之前,先決定誰可以讀它,以及保留多久。
階段的門,只有紀錄那麼可靠。紀錄裡的一個洞(記下發生了什麼,不是 agent 說了什麼),會讓「規則撐得住」看起來是真的,其實並不知道。
我沒有團隊數據。三層、審查的習慣、稽核的例行和各階段,是建在一個人使用上的設計。我沒有量過採用情況,也沒有追蹤團隊裡誰改了什麼。把它們當成要檢查的起點,不是結果。
代价和坑
负责人会变成瓶颈。如果每次规则改动都要经过两个人,大家就不再提改动,转而留私人副本,这正是你要解决的问题。让核心层保持小,这样走严格流程的改动就少,团队层则让它改得快。
审查规则没什么光彩。没人会因为一条没加的规则而被感谢。把负责人的时间排进某个人的计划里,否则审查会变成走过场。
审查者得有能力判断这条规则。一条关于部署路径的规则,让一个从没部署过的人审查,只是一次拼写检查。
太多本地 override,就是 fork。如果大多数用户带着同样的 override,它就该放进团队层。时不时看看 override,把常见的提升上去。
日志里有关于人的东西。一份记录每次调用的日志,会显示某人什么时候工作、让 agent 去碰什么。在集中收集之前,先定谁可以读它,保存多久。
阶段关卡的好坏取决于记录。日志里的漏洞(记下发生了什么,而不是 agent 说了什么),会让“规则站得住”看起来是真的,实际上并不知道。
我没有团队数据。三层划分、审查习惯、审计例行动作和各个阶段,是根据一个人的使用设计出来的。我没有测过团队里的采用情况,也没有跟踪过谁改了什么。把它们当作要验证的起点,不要当结果。
When to delete it
The three-layer split exists because the platform gives you files and no way to own them. If your platform lets an organisation publish rules centrally, with its own review, audit and roll-out, use that for the core layer and keep only the team layer yourself. I have not checked what Copilot offers here today, so look at its current docs before building your own.
The review questions do not retire. They are how you decide whether any rule, skill or agent deserves to exist.
什麼時候可以刪掉
三層的劃分存在,是因為平台給你檔案,卻沒有辦法擁有它們。如果你的平台讓組織集中發布規則,並附帶自己的審查、稽核和推行,核心層就用它,只留團隊層自己做。Copilot 今天在這方面提供什麼,我沒有確認,所以在自己動手之前,先看它目前的文件。
審查的問題不會退役。它們是你決定任何規則、skill 或 agent 值不值得存在的辦法。
什么时候可以删掉
三层划分之所以存在,是因为平台给你文件,却没有给你管理这些文件的办法。如果你的平台允许组织集中发布规则,并自带审查、审计和推广,核心层就用它的,自己只留团队层。Copilot 现在在这方面提供什么,我没查过,所以自己动手建之前,先看它当前的文档。
审查的那些问题不会退役。你就是用它们来决定,任何规则、skill 或 agent 值不值得存在。
Try it on your own setup
No harness needed. Open your agent in your own repository and paste:
Look at the files in this repository that tell an AI agent what to do or what it may not do (instruction files, skills, agent definitions, hook and permission settings). For each one, tell me from git history who last changed it, when, and whether the commit had a reviewer other than the author. List any rule that is written in more than one file. Then list what records exist of what the agent did here (logs, transcripts, reports) and who could read them. Mark every gap. Do not change any files.在你自己的環境試試
不用裝 harness。在你自己的倉庫裡打開 agent,貼上:
看這個倉庫裡告訴 AI agent 該做什麼、不可以做什麼的檔案(指令檔、skill、agent 定義、hook 和權限設定)。每一個,從 git 歷史告訴我:最後是誰改的、什麼時候,以及那個 commit 除了作者之外有沒有審查者。列出寫在不只一個檔案裡的規則。然後列出有哪些紀錄記下了 agent 在這裡做過什麼(日誌、對話紀錄、報告),以及誰能讀它們。標出每一個缺口。不要改任何檔案。在你自己的环境里试试
不用装 harness。在你自己的仓库里打开 agent,粘贴:
看看这个仓库里告诉 AI agent 该做什么或不许做什么的文件(指令文件、skill、agent 定义、hook 和权限设置)。对每一个,根据 git 历史告诉我:最后是谁改的,什么时候改的,这次提交有没有作者之外的审查者。列出写在不止一个文件里的规则。然后列出有哪些关于 agent 在这里做了什么的记录(日志、对话记录、报告),以及谁能读到它们。把每个缺口都标出来。不要修改任何文件。Go deeper
- Guard the files that hold the rules: how the fence is held and when a person opens it.
- Instructions and skills: where rules live and why one rule has one source.
- Record what happened, not what the agent said: what to record and how to read it.
- People and teams: what stays with a person, and how to start a newcomer.
- What we cut: the same admission questions, applied to my own setup.
延伸閱讀
- 保護規則本身的檔案:圍欄怎麼守住,什麼時候由人打開。
- 指令與 skill:只載入需要的:規則放在哪裡,以及為什麼一條規則只有一個來源。
- 記下發生了什麼,不是 agent 說了什麼:記什麼,以及怎麼讀。
- 人與團隊:留給人的事:什麼事留給人,以及怎麼帶新人上手。
- 我砍掉了什麼,數據怎麼說:同樣的准入問題,用在我自己的設定上。
延伸阅读
- 保护规则本身的文件:围栏怎么守住,人什么时候打开它。
- 指令与 skill:只加载需要的:规则放在哪里,为什么一条规则只有一个来源。
- 记下发生了什么,而不是 agent 说了什么:该记录什么,怎么读。
- 人与团队:留给人的事:留给人的事,以及怎么让新人上手。
- 我砍掉了什么,数据怎么说:同样的准入问题,用在我自己的配置上。
You can stop here: that is the whole idea. The next part shows where it runs, so you can look inside.讀到這裡就夠了,這就是整個想法。下一部分告訴你它在哪裡運行,可以進去看看。读到这里就够了,核心思路就是这些。下一部分告诉你它在哪里跑,可以进去看看。
In my practice (Copilot Harness)實作实战
Copilot Harness is my open-source harness for VS Code Copilot.
Repository: https://github.com/Smars-Bin-Hu/copilot-agentic-harness
Get started: clone it, open it in VS Code, and type /harness-rookie-get-me-ready in Copilot Chat. You need Python 3.9 or later and git.
Copilot Harness 是我開源的 VS Code Copilot harness。
倉庫: https://github.com/Smars-Bin-Hu/copilot-agentic-harness
開始:clone 下來,用 VS Code 打開,在 Copilot Chat 裡輸入 /harness-rookie-get-me-ready。需要 Python 3.9 以上和 git。
Copilot Harness 是我开源的 VS Code Copilot harness。
仓库: https://github.com/Smars-Bin-Hu/copilot-agentic-harness
上手:把仓库 clone 下来,用 VS Code 打开,在 Copilot Chat 里输入 /harness-rookie-get-me-ready。需要 Python 3.9 及以上版本和 git。
Explore it in the harness
Overrides, the health check, the fenced rule files and the logs all run in Copilot Harness. The harness can show them to you with the real files. After the setup above, type:
/harness-rookie-wondering I have read the chapter "Roll out and govern a harness". Teach me how this harness lets a team customise it without forking it (policy overrides, the health check that lists them), how it guards its own rule files, and what its logs and reports record. Open the real files with me, and show where a team's changes go and where they must not go.It teaches one small piece at a time, stops to ask if you are following, and opens the files with you.
在 harness 裡探索
override、健康檢查、被圍起來的規則檔和紀錄,都在 Copilot Harness 裡執行。harness 可以用真實的檔案帶你看。照上面的說明準備好之後,輸入:
/harness-rookie-wondering 我讀完了「落地與治理」這一章。請教我這個 harness 怎麼讓團隊客製化卻不用分叉(policy override,和列出它們的健康檢查),怎麼保護它自己的規則檔,以及它的紀錄和報告記下什麼。和我一起打開真實的檔案,讓我看團隊的改動該放在哪裡,不該放在哪裡。它一次教一小塊,停下來確認你跟得上,然後和你一起打開檔案。
在 harness 里探索
override、健康检查、被围起来的规则文件和日志,都在 Copilot Harness 里跑着。harness 可以带着真实的文件把它们展示给你。按上面的说明准备好之后,输入:
/harness-rookie-wondering 我读完了“落地与治理”这一章。请教我这个 harness 是怎么让团队定制它而不用 fork 的(策略 override,以及列出它们的健康检查),它怎么守住自己的规则文件,以及它的日志和报告记录了什么。带我打开真实的文件,让我看看团队的改动该放在哪里、不该放在哪里。它一次只教一小块,停下来确认你跟上了,再和你一起打开文件。