> Harness EngineeringHarness EngineeringHarness Engineering The engineering outside the model模型之外的工程模型之外的工程

C

Patterns you can copy可以照抄的模式可以照抄的模式

This appendix is a shelf of small patterns. Each one has the problem in a line, the pattern in a few lines, a real file from my harness to copy from, and the chapter that explains why. They are examples to adapt, not to paste. The files are the real ones at the pinned tag, so they are longer and more specific than your first version should be. Check each one in your own setup after you copy it. If you do not know where to start, take the safety patterns first (refuse a command, keep approvals for the person), then the ones that save context, then the ones for long work. Each pattern has a Limit line, taken from the chapter it links to.

這個附錄是一個小模式的架子。每個模式有:一行的問題、幾行的模式、一個你可以照著抄的我的 harness 的真實檔案,以及解釋原因的章節。它們是讓你改寫的例子,不是讓你整份貼上的。這些檔案是釘住的 tag 上的真實檔案,所以比你的第一版應該有的更長、更具體。抄過去之後,在你自己的環境裡把每一個都檢查一遍。如果不知道從哪裡開始,先拿安全的模式(拒絕一個指令,把批准留給人),然後是省上下文的,再來是給長任務用的。每個模式都有一行限制,取自它連結的那一章。

这个附录是一个小模式的书架。每个模式有一行问题,几行做法,一个可以照着抄的、来自我的 harness 的真实文件,以及讲道理的那一章。它们是拿来改的例子,不是拿来粘贴的。这些文件是钉住的 tag 上的真实文件,所以比你的第一版应有的样子更长、更具体。抄过去之后,要在你自己的环境里逐个检查。如果不知道从哪里开始,先看安全类的模式(拒绝一条命令、审批留给人),再看省上下文的,最后看长任务用的。每个模式都有一行局限,取自它所链接的那一章。

Put the core limits on one page

Problem. The agent guesses paths and commands, or tidies files you changed.

Pattern. Keep a short always-loaded page. Put in it only what the model would get wrong without it, and put it first. Two limits are enough to begin.

Two core limits from the shipped rules page: look before you act, and keep the user's own changes.
- Look at the real files before you act. Do not guess a path, a command, a setting or how to test.
- Keep the changes the user already made. Do not touch unrelated files.

Limit. A page that grows long stops being read; every line must earn its place.

More in Instructions and skills and A minimal harness.

把核心限制放在一頁上

問題。agent 亂猜路徑和指令,或者把你改過的檔案「整理」掉。

模式。保留一頁永遠載入的短頁面。只放沒有它模型就會做錯的東西,並放在最前面。開始時,兩條限制就夠了。

出貨的規則頁裡的兩條核心限制:動手前先看,並保留使用者自己的改動。
- Look at the real files before you act. Do not guess a path, a command, a setting or how to test.
- Keep the changes the user already made. Do not touch unrelated files.

限制。越寫越長的頁面就不會被讀了;每一行都必須有存在的理由。

更多在 指令與 skill:只載入需要的 和 30 分鐘搭一個最小 harness。

把核心限制放在一页上

问题。 agent 乱猜路径和命令,或者把你改的文件“整理”掉。

做法。 保留一页简短的、始终加载的规则。只放没有它模型就会做错的内容,并放在最前面。开头有两条限制就够了。

随 harness 发布的规则页里的两条核心限制:先看再动手,保留用户自己的改动。
- Look at the real files before you act. Do not guess a path, a command, a setting or how to test.
- Keep the changes the user already made. Do not touch unrelated files.

局限。 变长的页面就没人读了;每一行都要有存在的理由。

更多内容见指令与 skill:只加载需要的和30 分钟搭一个最小 harness。

Load rules only for the files they apply to

Problem. A rule that matters for one kind of file costs room in every chat.

Pattern. Put the rule in an instruction file with an applyTo pattern. It loads when the agent works on a matching file and costs nothing otherwise.

The header of a file-based instruction: a description and an applyTo pattern.
---
description: 'Guidelines for creating high-quality Agent Skills for GitHub Copilot'
applyTo: '.github/skills/**/SKILL.md'
---

Limit. It is a request to the model, not a rule the platform enforces.

More in Instructions and skills.

只為適用的檔案載入規則

問題。只對某一種檔案重要的規則,在每個對話裡都占空間。

模式。把規則放進帶 applyTo 樣式的指令檔。agent 處理符合的檔案時才載入,其他時候不花任何東西。

依檔案載入的指令的標頭:一段描述和一個 applyTo 樣式。
---
description: 'Guidelines for creating high-quality Agent Skills for GitHub Copilot'
applyTo: '.github/skills/**/SKILL.md'
---

限制。這是對模型的請求,不是平台強制的規則。

更多在 指令與 skill:只載入需要的。

规则只为它适用的文件加载

问题。 一条只对某一类文件要紧的规则,在每个对话里都占地方。

做法。 把规则放进带 applyTo 匹配模式的指令文件。agent 处理匹配的文件时才加载,其余时候不占任何空间。

按文件加载的指令的头部:一段描述和一个 applyTo 匹配模式。
---
description: 'Guidelines for creating high-quality Agent Skills for GitHub Copilot'
applyTo: '.github/skills/**/SKILL.md'
---

局限。 这是对模型的请求,不是平台强制执行的规则。

更多内容见指令与 skill:只加载需要的。

One hook entry for every moment

Problem. Several hook scripts, each with its own timeout and shell, are hard to keep in step.

Pattern. Make the configuration file only say which moments to call, and point every moment to one program. The program decides what to do. Set a time limit, and remember the file is read when the window starts.

The entry for the moment before a tool runs: it only names the program and its time limit.
    "PreToolUse": [
      {
        "type": "command",
        "command": "python3 .harness/engine/hook.py",
        "windows": "python .harness/engine/hook.py",
        "bash": "python3 .harness/engine/hook.py",
        "powershell": "python .harness/engine/hook.py",
        "cwd": ".",
        "timeout": 30,
        "timeoutSec": 30
      }
    ],

Limit. A hook that times out is treated as a pass, so keep it fast.

More in Hooks and Build the enforcement layer like software.

每個時刻共用一個 hook 入口

問題。好幾個 hook 腳本,各有自己的逾時和 shell,很難保持一致。

模式。讓設定檔只說要在哪些時刻呼叫,並把每個時刻都指向同一個程式。由程式決定要做什麼。設定時間上限,並記得這個檔案是在視窗啟動時讀的。

工具執行之前那個時刻的入口:它只指名程式和它的時間上限。
    "PreToolUse": [
      {
        "type": "command",
        "command": "python3 .harness/engine/hook.py",
        "windows": "python .harness/engine/hook.py",
        "bash": "python3 .harness/engine/hook.py",
        "powershell": "python .harness/engine/hook.py",
        "cwd": ".",
        "timeout": 30,
        "timeoutSec": 30
      }
    ],

限制。逾時的 hook 會被當成通過,所以要讓它快。

更多在 Hooks:每次呼叫都會經過的執行點 和 把執行層當軟體來設計。

所有时机只用一个 hook 入口

问题。 好几个 hook 脚本,各有各的超时和 shell,很难保持一致。

做法。 让配置文件只说明在哪些时机调用,并让每个时机都指向同一个程序。做什么由这个程序决定。设一个时间限制,并记住这个文件是在窗口启动时读取的。

工具运行之前那个时机的入口:它只写出程序的名字和时间限制。
    "PreToolUse": [
      {
        "type": "command",
        "command": "python3 .harness/engine/hook.py",
        "windows": "python .harness/engine/hook.py",
        "bash": "python3 .harness/engine/hook.py",
        "powershell": "python .harness/engine/hook.py",
        "cwd": ".",
        "timeout": 30,
        "timeoutSec": 30
      }
    ],

局限。 超时的 hook 会被当作通过,所以要让它快。

更多内容见Hook:每次调用都会经过的执行点和把执行层当软件来设计。

Refuse a dangerous command, with a reason

Problem. A command whose damage cannot be undone, such as recursive deletion of a root or home folder, should never run.

Pattern. Write a pattern and a why sentence for each. The agent reads the reason, so say what the command would do. Keep the pattern narrow, because a false refusal is a stuck task. It stops common spellings, not every spelling.

One real refusal rule: recursive force-delete of the root, home or current folder, with a reason the agent can read.
      {
        "why": {"en": "it recursively deletes the root, the home folder or the current folder", "zh": "递归删除根目录、家目录或当前目录"},
        "pattern": "{cmd}rm\\s+(?:-[a-z]+\\s+)*-[a-z]*(?:r[a-z]*f|f[a-z]*r)[a-z]*\\s+(?:/|~|\\$home|\\*|\\.|\\.\\.)/?\\*?(?:\\s|$|[;&|])"
      },

Limit. This is a speed bump, not a boundary: it stops common spellings. For things that must never be touched, do not hand them over (Some things you never hand over).

More in Asking is not a limit and Hooks.

拒絕危險的指令,並附上原因

問題。造成的傷害無法復原的指令,例如遞迴刪除根目錄或家目錄,絕不該執行。

模式。每一條寫一個樣式和一句 why。agent 會讀這個原因,所以要說這個指令會做什麼。樣式要窄,因為錯誤的拒絕就是一個卡住的任務。它擋得住常見的寫法,不是每一種寫法。

一條真實的拒絕規則:遞迴強制刪除根目錄、家目錄或目前的資料夾,附上 agent 讀得懂的原因。
      {
        "why": {"en": "it recursively deletes the root, the home folder or the current folder", "zh": "递归删除根目录、家目录或当前目录"},
        "pattern": "{cmd}rm\\s+(?:-[a-z]+\\s+)*-[a-z]*(?:r[a-z]*f|f[a-z]*r)[a-z]*\\s+(?:/|~|\\$home|\\*|\\.|\\.\\.)/?\\*?(?:\\s|$|[;&|])"
      },

限制。這是減速丘,不是邊界:它擋住常見的寫法。對絕不能被碰的東西,不要交出去(有些東西根本不給)。

更多在 詢問不是限制 和 Hooks:每次呼叫都會經過的執行點。

拒绝危险命令,并给出理由

问题。 造成的损害无法挽回的命令,比如递归删除根目录或主目录,永远不该运行。

做法。 为每一条写一个匹配模式和一句 why。agent 会读这个理由,所以要写清这条命令会做什么。匹配模式要窄,因为一次误拒就是一个卡住的任务。它拦得住常见的写法,拦不住所有的写法。

一条真实的拒绝规则:对根目录、主目录或当前文件夹做递归强制删除,附上 agent 读得懂的理由。
      {
        "why": {"en": "it recursively deletes the root, the home folder or the current folder", "zh": "递归删除根目录、家目录或当前目录"},
        "pattern": "{cmd}rm\\s+(?:-[a-z]+\\s+)*-[a-z]*(?:r[a-z]*f|f[a-z]*r)[a-z]*\\s+(?:/|~|\\$home|\\*|\\.|\\.\\.)/?\\*?(?:\\s|$|[;&|])"
      },

局限。 这是个减速带,不是边界:它只拦常见的写法。对那些绝不能碰的东西,不要交出去(有些东西根本不给)。

更多内容见询问不是限制和Hook:每次调用都会经过的执行点。

Keep approvals for the person's terminal

Problem. If the agent can run the approval command, the approval means nothing.

Pattern. Refuse, in the same hook, every command that grants a right. The reason tells the agent to ask the person to run it in their own terminal. Test it by asking the agent to run one.

A refusal for the commands only a person may run: approvals, waivers, switching unattended mode on.
      {
        "why": {"en": "only the user may run these, in their own terminal: approving a plan (task approve-plan), confirming the requirement (task confirm-req), approving a write-back (task approve-promote), recovering a promote that failed halfway (task recover), giving more checks, waiving them or dismissing one (task review extend, task review waive, task review dismiss), pausing and resuming a task (task pause, task resume, and all at once: task offwork, task onwork), switching autorun on (task autorun on), serving the board with buttons that act (task board, task board --serve; an agent writes the page with task board --once), approving a git command (approve-command), switching admin mode on (admin on). Tell the user to run the command; do not run it yourself", "zh": "批准计划(task approve-plan)、批准回写(task approve-promote)、恢复中途出错的 promote(task recover)、再给检查次数、放行或作废一次检查(task review extend、task review waive、task review dismiss)、搁置和恢复任务(task pause、task resume,以及一次全部:task offwork、task onwork)、开 autorun(task autorun on)、启动能操作的看板服务(task board、task board --serve;agent 只能用 task board --once 生成页面)、批准 git 命令(approve-command)、开 admin 模式(admin on)只能由用户在自己的终端里运行。告诉用户运行这条命令,不要自己运行"},
        "pattern": "\\b(?:cli\\.py|harness(?:\\.cmd)?)\\s+(?:task\\s+(?:approve-plan|confirm-req|approve-promote|recover|pause|resume|offwork|onwork|autorun\\s+on|review\\s+(?:extend|waive|dismiss)|board\\b(?![^;&|\\n]*\\s--once\\b))|approve-command|admin\\s+on)\\b"
      }

Limit. It works only while the hook runs and its files are guarded.

More in Two gates: where a person approves and Guard the files that hold the rules.

把批准留給人的終端機

問題。如果 agent 能執行批准的指令,批准就沒有意義。

模式。在同一個 hook 裡,拒絕每一個授予權限的指令。原因要告訴 agent,請人在他自己的終端機裡執行。請 agent 執行其中一個,來測試它。

對只有人才能執行的指令的拒絕:批准、豁免、開啟無人值守模式。
      {
        "why": {"en": "only the user may run these, in their own terminal: approving a plan (task approve-plan), confirming the requirement (task confirm-req), approving a write-back (task approve-promote), recovering a promote that failed halfway (task recover), giving more checks, waiving them or dismissing one (task review extend, task review waive, task review dismiss), pausing and resuming a task (task pause, task resume, and all at once: task offwork, task onwork), switching autorun on (task autorun on), serving the board with buttons that act (task board, task board --serve; an agent writes the page with task board --once), approving a git command (approve-command), switching admin mode on (admin on). Tell the user to run the command; do not run it yourself", "zh": "批准计划(task approve-plan)、批准回写(task approve-promote)、恢复中途出错的 promote(task recover)、再给检查次数、放行或作废一次检查(task review extend、task review waive、task review dismiss)、搁置和恢复任务(task pause、task resume,以及一次全部:task offwork、task onwork)、开 autorun(task autorun on)、启动能操作的看板服务(task board、task board --serve;agent 只能用 task board --once 生成页面)、批准 git 命令(approve-command)、开 admin 模式(admin on)只能由用户在自己的终端里运行。告诉用户运行这条命令,不要自己运行"},
        "pattern": "\\b(?:cli\\.py|harness(?:\\.cmd)?)\\s+(?:task\\s+(?:approve-plan|confirm-req|approve-promote|recover|pause|resume|offwork|onwork|autorun\\s+on|review\\s+(?:extend|waive|dismiss)|board\\b(?![^;&|\\n]*\\s--once\\b))|approve-command|admin\\s+on)\\b"
      }

限制。只有在 hook 執行、它的檔案被保護時才行得通。

更多在 兩道門:人在哪裡批准 和 保護規則本身的檔案。

审批留在人的终端里

问题。 如果 agent 能运行审批命令,审批就没有意义。

做法。 在同一个 hook 里,拒绝每一条授予权限的命令。理由告诉 agent,请人到自己的终端里去运行。测一下:让 agent 运行其中一条。

对只有人才能运行的命令的拒绝:审批、豁免、打开无人值守模式。
      {
        "why": {"en": "only the user may run these, in their own terminal: approving a plan (task approve-plan), confirming the requirement (task confirm-req), approving a write-back (task approve-promote), recovering a promote that failed halfway (task recover), giving more checks, waiving them or dismissing one (task review extend, task review waive, task review dismiss), pausing and resuming a task (task pause, task resume, and all at once: task offwork, task onwork), switching autorun on (task autorun on), serving the board with buttons that act (task board, task board --serve; an agent writes the page with task board --once), approving a git command (approve-command), switching admin mode on (admin on). Tell the user to run the command; do not run it yourself", "zh": "批准计划(task approve-plan)、批准回写(task approve-promote)、恢复中途出错的 promote(task recover)、再给检查次数、放行或作废一次检查(task review extend、task review waive、task review dismiss)、搁置和恢复任务(task pause、task resume,以及一次全部:task offwork、task onwork)、开 autorun(task autorun on)、启动能操作的看板服务(task board、task board --serve;agent 只能用 task board --once 生成页面)、批准 git 命令(approve-command)、开 admin 模式(admin on)只能由用户在自己的终端里运行。告诉用户运行这条命令,不要自己运行"},
        "pattern": "\\b(?:cli\\.py|harness(?:\\.cmd)?)\\s+(?:task\\s+(?:approve-plan|confirm-req|approve-promote|recover|pause|resume|offwork|onwork|autorun\\s+on|review\\s+(?:extend|waive|dismiss)|board\\b(?![^;&|\\n]*\\s--once\\b))|approve-command|admin\\s+on)\\b"
      }

局限。 只有在 hook 运行、并且它的文件受到保护的时候才有效。

更多内容见两道门:人在哪里审批和保护规则本身的文件。

Mark a skill that only a person may start

Problem. A skill that spends money or hands over rights should not start because the model thought it fit.

Pattern. Set disable-model-invocation: true, and say in the description that the agent must not call it. This limits who starts the skill. It does not limit what the skill does once started.

The top of a skill only the user may start: the flag in the header and the sentence in the description.
---
name: harness-autorun
description: 'autorun (beta): the agent that holds a task works down TODO.md without the user watching every step, and stops only for what a person must decide. This skill takes the user through getting ready and switching autorun on, and sets the rules while it runs. Use only when the user clearly types /harness-autorun; an agent must not call it by itself. Keywords: autorun, unattended, run to the end, keep going, no need to watch.'
argument-hint: 'Task name (optional; the current task by default)'
disable-model-invocation: true
type: workflow
specificTo: generic
---

Limit. It limits who starts the skill, not what the skill does.

More in Instructions and skills and Unattended: when it must stop.

標記一個只有人能啟動的 skill

問題。一個花錢或交出權限的 skill,不該因為模型覺得合適就啟動。

模式。設定 disable-model-invocation: true,並在描述裡說明 agent 不可以呼叫它。這限制的是誰來啟動 skill。它不限制 skill 啟動之後做什麼。

一個只有使用者能啟動的 skill 的開頭:標頭裡的旗標,和描述裡的那句話。
---
name: harness-autorun
description: 'autorun (beta): the agent that holds a task works down TODO.md without the user watching every step, and stops only for what a person must decide. This skill takes the user through getting ready and switching autorun on, and sets the rules while it runs. Use only when the user clearly types /harness-autorun; an agent must not call it by itself. Keywords: autorun, unattended, run to the end, keep going, no need to watch.'
argument-hint: 'Task name (optional; the current task by default)'
disable-model-invocation: true
type: workflow
specificTo: generic
---

限制。它限制誰來啟動 skill,不限制 skill 做什麼。

更多在 指令與 skill:只載入需要的 和 無人值守:什麼時候必須停。

标出只有人才能启动的 skill

问题。 一个会花钱或者会交出权限的 skill,不该因为模型觉得合适就启动。

做法。 设置 disable-model-invocation: true,并在描述里写明 agent 不得调用它。这限制的是谁来启动这个 skill,不限制它启动之后做什么。

只有用户才能启动的 skill 的开头:头部的标志,和描述里的那句话。
---
name: harness-autorun
description: 'autorun (beta): the agent that holds a task works down TODO.md without the user watching every step, and stops only for what a person must decide. This skill takes the user through getting ready and switching autorun on, and sets the rules while it runs. Use only when the user clearly types /harness-autorun; an agent must not call it by itself. Keywords: autorun, unattended, run to the end, keep going, no need to watch.'
argument-hint: 'Task name (optional; the current task by default)'
disable-model-invocation: true
type: workflow
specificTo: generic
---

局限。 它限制谁来启动 skill,不限制 skill 做什么。

更多内容见指令与 skill:只加载需要的和无人值守:什么时候必须停。

A read-only helper

Problem. You want an agent to read a lot without being able to change anything.

Pattern. Create a custom agent whose tools list has only read and search, and which cannot call other agents. The tool list is the limit; the "do not" lines in the body are requests. Say in the body what the helper must hand back.

A read-only helper: the tool list is read and search only, and it calls no other agent.
---
name: mapper
description: The read-only chunk reader. After the user types /generic-mapreduce, the default agent calls several in parallel: each reads the part it is given and hands in only a summary with sources. It changes no file and runs no command.
user-invocable: false
agents: []
model: ['Claude Sonnet 5.5 (copilot)', 'Claude Sonnet 5.5', 'Claude Haiku 5.5 (copilot)', 'Claude Haiku 5.5', 'Claude Haiku 4.5 (copilot)', 'Claude Haiku 4.5']
tools: ['read', 'search']
---

Limit. Each helper starts with an empty context, so several helpers cost several times one agent.

More in Custom agents and Use subagents sparingly.

一個唯讀的幫手

問題。你想讓 agent 讀很多東西,卻不能改任何東西。

模式。建立一個 custom agent,它的 tools 清單只有讀和搜尋,而且不能呼叫別的 agent。工具清單是限制;內文裡的「不要」是請求。在內文裡說明這個幫手必須交回什麼。

一個唯讀的幫手:工具清單只有讀和搜尋,而且它不呼叫其他 agent。
---
name: mapper
description: The read-only chunk reader. After the user types /generic-mapreduce, the default agent calls several in parallel: each reads the part it is given and hands in only a summary with sources. It changes no file and runs no command.
user-invocable: false
agents: []
model: ['Claude Sonnet 5.5 (copilot)', 'Claude Sonnet 5.5', 'Claude Haiku 5.5 (copilot)', 'Claude Haiku 5.5', 'Claude Haiku 4.5 (copilot)', 'Claude Haiku 4.5']
tools: ['read', 'search']
---

限制。每個幫手都從空的上下文開始,所以好幾個幫手的花費是一個 agent 的好幾倍。

更多在 Custom agent:固定模型和工具的角色 和 慎用子 agent。

只读的帮手

问题。 你想让一个 agent 大量阅读,却不能改任何东西。

做法。 建一个自定义 agent,它的 tools 列表里只有读和搜索,也不能调用别的 agent。工具列表才是限制;正文里的“不要……”是请求。在正文里写明这个帮手必须交回什么。

一个只读的帮手:工具列表只有读和搜索,也不调用别的 agent。
---
name: mapper
description: The read-only chunk reader. After the user types /generic-mapreduce, the default agent calls several in parallel: each reads the part it is given and hands in only a summary with sources. It changes no file and runs no command.
user-invocable: false
agents: []
model: ['Claude Sonnet 5.5 (copilot)', 'Claude Sonnet 5.5', 'Claude Haiku 5.5 (copilot)', 'Claude Haiku 5.5', 'Claude Haiku 4.5 (copilot)', 'Claude Haiku 4.5']
tools: ['read', 'search']
---

局限。 每个帮手都从空白的上下文开始,所以几个帮手的成本是单个 agent 的好几倍。

更多内容见自定义 agent:固定模型和工具的角色和慎用子 agent。

Give a helper a brief it can use alone

Problem. A helper cannot see your conversation, so a vague call gets a vague answer.

Pattern. Write the question, the scope to read, and the items to hand back, with a length limit and a source for every conclusion.

A brief for a read-only helper: question, scope, what to hand in, length and sources.
```text
Question: <what to answer, in a sentence or two>

Scope: read only these.
- <path of a file or folder>
- <path of a file or folder>

To hand in:
- <item 1 the summary must have>
- <item 2 the summary must have>

Length: <N> lines at most. Every conclusion has its source (path:line).
Background: <a sentence or two it needs to know; delete this line if there is none>
```

More in Use subagents sparingly.

給幫手一份它能單獨使用的簡報

問題。幫手看不到你的對話,所以含糊的呼叫只會得到含糊的答案。

模式。寫下問題、要讀的範圍,和要交回的項目,附上長度限制,每個結論都要有來源。

給唯讀幫手的簡報:問題、範圍、要交什麼、長度和來源。
```text
Question: <what to answer, in a sentence or two>

Scope: read only these.
- <path of a file or folder>
- <path of a file or folder>

To hand in:
- <item 1 the summary must have>
- <item 2 the summary must have>

Length: <N> lines at most. Every conclusion has its source (path:line).
Background: <a sentence or two it needs to know; delete this line if there is none>
```

更多在 慎用子 agent。

给帮手一份它能独立使用的任务说明

问题。 帮手看不到你的对话,所以含糊的调用只会得到含糊的回答。

做法。 写明问题、要读的范围和要交回的条目,附上长度限制,并要求每个结论都给出来源。

给只读帮手的任务说明:问题、范围、要交回什么、长度和来源。
```text
Question: <what to answer, in a sentence or two>

Scope: read only these.
- <path of a file or folder>
- <path of a file or folder>

To hand in:
- <item 1 the summary must have>
- <item 2 the summary must have>

Length: <N> lines at most. Every conclusion has its source (path:line).
Background: <a sentence or two it needs to know; delete this line if there is none>
```

更多内容见慎用子 agent。

A checker that answers PASS or FAIL

Problem. A checker that writes essays gives a person nothing to count and a script nothing to read.

Pattern. Fix the first line to PASS or FAIL. Every finding names a file and a line and the rule it breaks. No advice, no fix, a length limit. Then a script can count passes and drop findings that point nowhere.

The fixed output of an independent checker: a verdict line, findings with file and line, a length cap.
## Output

The first line must be one of these two, with no character in front:

```text
VERDICT: PASS
VERDICT: FAIL
```

Then one line per finding, in this fixed format:

```text
- <file>:<line> <what does not match> | basis: <where the requirement or the rule says so>
```

- Every finding has `file:line`. What you cannot point to is not a finding: do not write it.
- Write no lines besides findings and evidence: no summary, no advice, no "also".
- For PASS, write one line of evidence per requirement item (with `file:line` too).
- 20 lines at most in all. Your answer is saved as written into `REVIEW/round-NNN/verdict.md`.

Limit. A model still makes mistakes as a checker; a false FAIL sends the author after a problem that is not there.

More in Make a pass count and Can a model check a model?.

回答 PASS 或 FAIL 的檢查者

問題。寫長篇大論的檢查者,讓人沒有東西可數,腳本也沒有東西可讀。

模式。把第一行固定為 PASS 或 FAIL。每個發現都指名一個檔案和一行,以及它違反的規則。不給建議,不給修法,有長度限制。這樣腳本就可以數通過的次數,並丟掉沒有指向任何地方的發現。

獨立檢查者的固定輸出:一行結論、附檔案和行號的發現、長度上限。
## Output

The first line must be one of these two, with no character in front:

```text
VERDICT: PASS
VERDICT: FAIL
```

Then one line per finding, in this fixed format:

```text
- <file>:<line> <what does not match> | basis: <where the requirement or the rule says so>
```

- Every finding has `file:line`. What you cannot point to is not a finding: do not write it.
- Write no lines besides findings and evidence: no summary, no advice, no "also".
- For PASS, write one line of evidence per requirement item (with `file:line` too).
- 20 lines at most in all. Your answer is saved as written into `REVIEW/round-NNN/verdict.md`.

限制。模型當檢查者還是會犯錯;錯誤的 FAIL 會讓作者去追一個不存在的問題。

更多在 讓「通過」可信 和 模型能檢查模型嗎。

只回答 PASS 或 FAIL 的检查者

问题。 一个写长篇大论的检查者,既没给人留下可数的东西,也没给脚本留下可读的东西。

做法。 把第一行固定为 PASS 或 FAIL。每条发现都写明文件、行号和违反的规则。不提建议,不给修复,有长度限制。这样脚本就能数通过的次数,并丢掉哪里都没指向的发现。

独立检查者的固定输出:一行结论、带文件和行号的发现、长度上限。
## Output

The first line must be one of these two, with no character in front:

```text
VERDICT: PASS
VERDICT: FAIL
```

Then one line per finding, in this fixed format:

```text
- <file>:<line> <what does not match> | basis: <where the requirement or the rule says so>
```

- Every finding has `file:line`. What you cannot point to is not a finding: do not write it.
- Write no lines besides findings and evidence: no summary, no advice, no "also".
- For PASS, write one line of evidence per requirement item (with `file:line` too).
- 20 lines at most in all. Your answer is saved as written into `REVIEW/round-NNN/verdict.md`.

局限。 模型当检查者仍然会出错;一次误报的 FAIL 会让作者去追一个不存在的问题。

更多内容见让“通过”可信和模型能检查模型吗。

Write the requirement on one page and have the person confirm it

Problem. The request is vague and shifts, and nobody can say later what was agreed.

Pattern. The agent writes a page with what to do, what not to do, when it is done, and an honest "not clear yet" list. A line at the top records whether the person confirmed it.

The requirement page: what to do, what not to do, done when, not clear yet, and who confirmed it.
# REQ: {name}

> The requirement. The agent writes it from the conversation with the user. It counts only after the user has read it. When the requirement changes, change this file and add a line at the end.
> The user's own documents (BRD, emails, screenshots) go in `REQ/`. The agent reads them and never changes them.

- **User confirmed**: <not yet / confirmed yyyy-mm-dd>

## What to do

<One or two paragraphs. What the user meant, with nothing of your own added>

## What not to do

<What is ruled out. Write "none" if there is nothing>

## Done when

<What counts as done, as items that can be checked. Number each item by who can show it; write "none" under a group with nothing>

### Shown by the task files

- [T1] <checked by the reviewer in the task files>

### Shown by a run the user does before the write-back

- [R1] <ENV>: <what the user runs and what the result must show; the result is saved in RUNS/<ENV>/>

### Shown after the write-back

- [A1] <checked in the environments after deployment (generic-test-guide); the reviewer does not judge it>

## Source

<Which files in `REQ/`, or "conversation">

## Not clear yet

<Questions for the user. Delete each one once it is answered. Write "none" if there is nothing>

## Changes

<yyyy-mm-dd: what changed, and why. Write "none" if there is nothing>

More in The agent writes the requirement, the person confirms it.

把需求寫在一頁上,並讓人確認

問題。請求含糊又會變,之後沒有人說得出當初同意了什麼。

模式。agent 寫一頁:要做什麼、不要做什麼、什麼時候算做完,以及一份誠實的「還不清楚」清單。最上面一行記下人有沒有確認。

需求頁:要做什麼、不要做什麼、做完的條件、還不清楚的,和誰確認的。
# REQ: {name}

> The requirement. The agent writes it from the conversation with the user. It counts only after the user has read it. When the requirement changes, change this file and add a line at the end.
> The user's own documents (BRD, emails, screenshots) go in `REQ/`. The agent reads them and never changes them.

- **User confirmed**: <not yet / confirmed yyyy-mm-dd>

## What to do

<One or two paragraphs. What the user meant, with nothing of your own added>

## What not to do

<What is ruled out. Write "none" if there is nothing>

## Done when

<What counts as done, as items that can be checked. Number each item by who can show it; write "none" under a group with nothing>

### Shown by the task files

- [T1] <checked by the reviewer in the task files>

### Shown by a run the user does before the write-back

- [R1] <ENV>: <what the user runs and what the result must show; the result is saved in RUNS/<ENV>/>

### Shown after the write-back

- [A1] <checked in the environments after deployment (generic-test-guide); the reviewer does not judge it>

## Source

<Which files in `REQ/`, or "conversation">

## Not clear yet

<Questions for the user. Delete each one once it is answered. Write "none" if there is nothing>

## Changes

<yyyy-mm-dd: what changed, and why. Write "none" if there is nothing>

更多在 需求由 agent 寫,人確認。

把需求写在一页上,并让人确认

问题。 请求含糊,还会变来变去,事后没人说得清当时约定了什么。

做法。 agent 写一页,写明要做什么、不做什么、什么时候算完成,以及一份诚实的“还不清楚”清单。顶上有一行,记录人是否确认过。

需求页:要做什么、不做什么、做到什么算完成、还不清楚的事,以及是谁确认的。
# REQ: {name}

> The requirement. The agent writes it from the conversation with the user. It counts only after the user has read it. When the requirement changes, change this file and add a line at the end.
> The user's own documents (BRD, emails, screenshots) go in `REQ/`. The agent reads them and never changes them.

- **User confirmed**: <not yet / confirmed yyyy-mm-dd>

## What to do

<One or two paragraphs. What the user meant, with nothing of your own added>

## What not to do

<What is ruled out. Write "none" if there is nothing>

## Done when

<What counts as done, as items that can be checked. Number each item by who can show it; write "none" under a group with nothing>

### Shown by the task files

- [T1] <checked by the reviewer in the task files>

### Shown by a run the user does before the write-back

- [R1] <ENV>: <what the user runs and what the result must show; the result is saved in RUNS/<ENV>/>

### Shown after the write-back

- [A1] <checked in the environments after deployment (generic-test-guide); the reviewer does not judge it>

## Source

<Which files in `REQ/`, or "conversation">

## Not clear yet

<Questions for the user. Delete each one once it is answered. Write "none" if there is nothing>

## Changes

<yyyy-mm-dd: what changed, and why. Write "none" if there is nothing>

更多内容见需求由 agent 写,人确认。

A handover file for the next session

Problem. A new chat knows nothing about the work done in the old one.

Pattern. Keep one short file a new session reads first: status, what is being done, the next step, what to read, and what the person decided. Update it before every stop. Do not trust it blindly: the agent writes it.

The handover file of a task: status, doing now, next step, files to read, decisions, open questions.
# TASK: {name}

> The handover file. A new session reads this file first, then what it points to. Keep it within one screen. Update it every time before you stop.

- **Kind**: {kind}
- **Tier**: {tier}
- **Created**: {created}
- **Updated**: <yyyy-mm-dd>
- **Status**: <in progress / waiting for the user to approve the plan / waiting for the user to accept / done>
- **Doing now**: <one sentence>
- **Next step**: <the one thing to do next>

## Files to read

<The files a new session should read, in order, with links. Write "none" if there is nothing>

## Decided

<What the user has decided, one per line, with the date. Write "none" if there is nothing>

## Open questions

<Five at most. Delete each one once it is solved. Write "none" if there is nothing>

Limit. The agent writes it, so it can be wrong; check what matters against the source.

More in Manage tasks, not chats and Long work across sessions.

給下一個會話的交接檔

問題。新的對話對舊對話裡做過的工作一無所知。

模式。保留一個新會話最先讀的短檔案:狀態、正在做什麼、下一步、要讀什麼,以及人做了什麼決定。每次停下來之前更新它。不要盲目相信它:是 agent 寫的。

任務的交接檔:狀態、現在在做什麼、下一步、要讀的檔案、決定、未解決的問題。
# TASK: {name}

> The handover file. A new session reads this file first, then what it points to. Keep it within one screen. Update it every time before you stop.

- **Kind**: {kind}
- **Tier**: {tier}
- **Created**: {created}
- **Updated**: <yyyy-mm-dd>
- **Status**: <in progress / waiting for the user to approve the plan / waiting for the user to accept / done>
- **Doing now**: <one sentence>
- **Next step**: <the one thing to do next>

## Files to read

<The files a new session should read, in order, with links. Write "none" if there is nothing>

## Decided

<What the user has decided, one per line, with the date. Write "none" if there is nothing>

## Open questions

<Five at most. Delete each one once it is solved. Write "none" if there is nothing>

限制。是 agent 寫的,所以可能是錯的;把重要的對照來源檢查。

更多在 管任務,不管對話 和 跨會話的長任務。

给下一个会话的交接文件

问题。 新对话对旧对话里做过的工作一无所知。

做法。 留一个简短的文件,新会话先读它:状态、正在做什么、下一步、该读什么,以及人做过的决定。每次停下之前都更新。不要盲目相信它:它是 agent 写的。

任务的交接文件:状态、正在做、下一步、要读的文件、决定、未解决的问题。
# TASK: {name}

> The handover file. A new session reads this file first, then what it points to. Keep it within one screen. Update it every time before you stop.

- **Kind**: {kind}
- **Tier**: {tier}
- **Created**: {created}
- **Updated**: <yyyy-mm-dd>
- **Status**: <in progress / waiting for the user to approve the plan / waiting for the user to accept / done>
- **Doing now**: <one sentence>
- **Next step**: <the one thing to do next>

## Files to read

<The files a new session should read, in order, with links. Write "none" if there is nothing>

## Decided

<What the user has decided, one per line, with the date. Write "none" if there is nothing>

## Open questions

<Five at most. Delete each one once it is solved. Write "none" if there is nothing>

局限。 它是 agent 写的,所以可能有错;要紧的内容要对照源头检查。

更多内容见管任务,不管对话和跨会话的长任务。

Write down the uses a person knew

Problem. A map of the code that a model or a script produced looks fine, and you have no way to know if it lost something later.

Pattern. A person writes a few uses they know are there, one per line, before the extractor exists. Every run of the map must find all of them.

Five known uses of the Spring sample: one object, the kind of use, the other object.
{"from": "controller:PetController", "kind": "uses", "to": "repository:PetTypeRepository"}
{"from": "controller:VetController", "kind": "uses", "to": "repository:VetRepository"}
{"from": "repository:OwnerRepository", "kind": "reads", "to": "entity:Owner"}
{"from": "entity:Owner", "kind": "maps", "to": "table:owners"}
{"from": "entity:Pet", "kind": "uses", "to": "entity:Visit"}

Limit. A short list shows the map can find a use. It does not show the map finds them all.

More in The toolkit.

寫下人知道的那些使用

問題。模型或腳本產生的程式碼地圖看起來沒問題,而你沒有辦法知道它之後有沒有弄丟東西。

模式。人在抽取器出現之前,寫下幾個他知道存在的使用,一行一個。地圖的每次執行,都必須找到所有這些。

Spring 範例的五個已知使用:一個物件、使用的種類、另一個物件。
{"from": "controller:PetController", "kind": "uses", "to": "repository:PetTypeRepository"}
{"from": "controller:VetController", "kind": "uses", "to": "repository:VetRepository"}
{"from": "repository:OwnerRepository", "kind": "reads", "to": "entity:Owner"}
{"from": "entity:Owner", "kind": "maps", "to": "table:owners"}
{"from": "entity:Pet", "kind": "uses", "to": "entity:Visit"}

限制。一份短清單,說明地圖找得到一個使用。它不說明地圖全都找得到。

更多在 Toolkit:用腳本畫出程式碼的地圖。

把人知道的调用关系写下来

问题。 模型或脚本生成的代码地图看起来没问题,你却没办法知道它之后有没有丢东西。

做法。 在抽取器还不存在的时候,由人写下几条他知道确实存在的调用关系,一行一条。每次生成地图,都必须把它们全部找出来。

Spring 示例里五条已知的调用关系:一个对象、调用的类型、另一个对象。
{"from": "controller:PetController", "kind": "uses", "to": "repository:PetTypeRepository"}
{"from": "controller:VetController", "kind": "uses", "to": "repository:VetRepository"}
{"from": "repository:OwnerRepository", "kind": "reads", "to": "entity:Owner"}
{"from": "entity:Owner", "kind": "maps", "to": "table:owners"}
{"from": "entity:Pet", "kind": "uses", "to": "entity:Visit"}

局限。 一份短清单只能说明地图找得到某些调用关系,不能说明它全都找得到。

更多内容见Toolkit:用脚本画出代码的地图。

Report an audit the same way every time

Problem. A check of a model's output ends as a paragraph, and two audits cannot be compared.

Pattern. A fixed report: pass or fail, a score per type, each difference with its file and line, the patterns, the readings that were corrected.

The audit report template: result, score per type, misses, false uses, patterns, corrected readings.
# Map audit

Date: <YYYY-MM-DD> · Map at: <repo>@<short commit>, ... · Toolkit: <name> (signature <signature from `toolkits` of kb audit>) · Sample: `kb audit --per-type <n> --seed <s>` · Bar: <0.95>

Result: **pass** | **fail**

## Score per type

| Type | Objects | Uses read | Uses in the map | Both | Recall | Precision | Pass |
| --- | --- | --- | --- | --- | --- | --- | --- |

## The map's misses (in the code, not in the map)

| Object | Use | Path:line | Why the toolkit misses it |
| --- | --- | --- | --- |

## The map's false uses (in the map, not in the code)

| Object | Use | Path | Why the toolkit sees it |
| --- | --- | --- | --- |

## Patterns

- <one line per form the toolkit gets wrong, with how common it looks in the code>

## Names the map could not place (`unresolved` of `kb map`, most used)

- <name: used by n; what it is>

## Readings corrected after checking the line

- <object, use: what was misread. Or "none">

## Not counted

- Dynamic code: <ids>

Limit. A small sample shows only large gaps.

More in Is the map right?.

每次都用同樣的方式報告抽查

問題。對模型輸出的檢查,最後變成一段文字,兩次抽查沒辦法比較。

模式。一份固定的報告:通過或失敗、每種類型的分數、每一處差異及其檔案和行號、規律、被修正的解讀。

抽查報告的範本:結果、每種類型的分數、漏掉的、假的使用、規律、被修正的解讀。
# Map audit

Date: <YYYY-MM-DD> · Map at: <repo>@<short commit>, ... · Toolkit: <name> (signature <signature from `toolkits` of kb audit>) · Sample: `kb audit --per-type <n> --seed <s>` · Bar: <0.95>

Result: **pass** | **fail**

## Score per type

| Type | Objects | Uses read | Uses in the map | Both | Recall | Precision | Pass |
| --- | --- | --- | --- | --- | --- | --- | --- |

## The map's misses (in the code, not in the map)

| Object | Use | Path:line | Why the toolkit misses it |
| --- | --- | --- | --- |

## The map's false uses (in the map, not in the code)

| Object | Use | Path | Why the toolkit sees it |
| --- | --- | --- | --- |

## Patterns

- <one line per form the toolkit gets wrong, with how common it looks in the code>

## Names the map could not place (`unresolved` of `kb map`, most used)

- <name: used by n; what it is>

## Readings corrected after checking the line

- <object, use: what was misread. Or "none">

## Not counted

- Dynamic code: <ids>

限制。小樣本只看得出大的差距。

更多在 地圖對不對:盲抽查。

每次都用同样的格式汇报一次抽查

问题。 对模型输出的检查,最后写成了一段文字,两次抽查没法比较。

做法。 一份固定的报告:通过还是失败,每种类型一个分数,每处差异附上文件和行号,出现的规律,以及被纠正过的读法。

抽查报告模板:结果、每种类型的分数、漏掉的、误报的调用关系、规律、被纠正的读法。
# Map audit

Date: <YYYY-MM-DD> · Map at: <repo>@<short commit>, ... · Toolkit: <name> (signature <signature from `toolkits` of kb audit>) · Sample: `kb audit --per-type <n> --seed <s>` · Bar: <0.95>

Result: **pass** | **fail**

## Score per type

| Type | Objects | Uses read | Uses in the map | Both | Recall | Precision | Pass |
| --- | --- | --- | --- | --- | --- | --- | --- |

## The map's misses (in the code, not in the map)

| Object | Use | Path:line | Why the toolkit misses it |
| --- | --- | --- | --- |

## The map's false uses (in the map, not in the code)

| Object | Use | Path | Why the toolkit sees it |
| --- | --- | --- | --- |

## Patterns

- <one line per form the toolkit gets wrong, with how common it looks in the code>

## Names the map could not place (`unresolved` of `kb map`, most used)

- <name: used by n; what it is>

## Readings corrected after checking the line

- <object, use: what was misread. Or "none">

## Not counted

- Dynamic code: <ids>

局限。 样本小,只看得出大的缺口。

更多内容见地图对不对:盲抽查。

Make a stop explain itself

Problem. An unattended run that stops with "ran into a problem" leaves the person to work out what happened.

Pattern. Tell the agent when to stop and when not to, and what the reason must contain: which step is stuck, why, and what the person must decide. The hook still judges the stops that facts can show.

When to stop by yourself, when not to, and how to write the reason for the person who comes back.
## Stop

| Case | Example |
| --- | --- |
| A trade-off the plan does not cover and that changes the result | Both tables have the field, defined differently, and the plan does not say which to use |
| Information is missing, and a guess may be wrong | The knowledge base has no definition of this metric |
| A step cannot be done | The file to change does not exist in the target repository; a needed permission is missing |
| Something out of scope has to be touched | A file outside the task folder, a git write command, a change to the plan |
| The plan itself turns out wrong | Following the plan would contradict the requirement |
| The reviewer names the same problem twice and you cannot fix it | Your understanding is off; more fixing just spins in place |

## Do not stop

| Case | What to do |
| --- | --- |
| A small implementation choice | Decide it and add a line to `LOG.md`: what you decided, and why |
| One tool call fails | Try once more another way |
| The reviewer did not pass it, and the problem is clear | Fix as it says and check again |
| The gate refuses once, and the reason has a next step | Do the next step. On a second refusal autorun stops by itself |

## How to write the reason

Write it for the user who comes back. One sentence that says: which step is stuck, why, and what they have to decide.

- Good: `Step 3: orders and orders_v2 both have updated_at, defined differently, and the plan does not say which to use. Yours to decide.`
- Bad: `Ran into a problem`

More in Unattended: when it must stop.

讓一次停止自己說明原因

問題。無人值守的執行以「遇到問題」停下來,讓人自己去弄清楚發生了什麼。

模式。告訴 agent 什麼時候該停、什麼時候不該停,以及原因必須包含什麼:哪一步卡住了、為什麼、人必須決定什麼。事實能顯示的停止,仍然由 hook 判斷。

什麼時候自己停、什麼時候不停,以及怎麼為回來的人寫下原因。
## Stop

| Case | Example |
| --- | --- |
| A trade-off the plan does not cover and that changes the result | Both tables have the field, defined differently, and the plan does not say which to use |
| Information is missing, and a guess may be wrong | The knowledge base has no definition of this metric |
| A step cannot be done | The file to change does not exist in the target repository; a needed permission is missing |
| Something out of scope has to be touched | A file outside the task folder, a git write command, a change to the plan |
| The plan itself turns out wrong | Following the plan would contradict the requirement |
| The reviewer names the same problem twice and you cannot fix it | Your understanding is off; more fixing just spins in place |

## Do not stop

| Case | What to do |
| --- | --- |
| A small implementation choice | Decide it and add a line to `LOG.md`: what you decided, and why |
| One tool call fails | Try once more another way |
| The reviewer did not pass it, and the problem is clear | Fix as it says and check again |
| The gate refuses once, and the reason has a next step | Do the next step. On a second refusal autorun stops by itself |

## How to write the reason

Write it for the user who comes back. One sentence that says: which step is stuck, why, and what they have to decide.

- Good: `Step 3: orders and orders_v2 both have updated_at, defined differently, and the plan does not say which to use. Yours to decide.`
- Bad: `Ran into a problem`

更多在 無人值守:什麼時候必須停。

让每次停下都自己说明原因

问题。 无人值守的运行以“遇到了问题”停下,留给人去弄清发生了什么。

做法。 告诉 agent 什么时候该停、什么时候不该停,以及理由里必须有什么:哪一步卡住了、为什么、人要决定什么。能用事实判断出来的停止,仍然由 hook 来判断。

什么时候该自己停、什么时候不该停,以及怎么给回来的人写理由。
## Stop

| Case | Example |
| --- | --- |
| A trade-off the plan does not cover and that changes the result | Both tables have the field, defined differently, and the plan does not say which to use |
| Information is missing, and a guess may be wrong | The knowledge base has no definition of this metric |
| A step cannot be done | The file to change does not exist in the target repository; a needed permission is missing |
| Something out of scope has to be touched | A file outside the task folder, a git write command, a change to the plan |
| The plan itself turns out wrong | Following the plan would contradict the requirement |
| The reviewer names the same problem twice and you cannot fix it | Your understanding is off; more fixing just spins in place |

## Do not stop

| Case | What to do |
| --- | --- |
| A small implementation choice | Decide it and add a line to `LOG.md`: what you decided, and why |
| One tool call fails | Try once more another way |
| The reviewer did not pass it, and the problem is clear | Fix as it says and check again |
| The gate refuses once, and the reason has a next step | Do the next step. On a second refusal autorun stops by itself |

## How to write the reason

Write it for the user who comes back. One sentence that says: which step is stuck, why, and what they have to decide.

- Good: `Step 3: orders and orders_v2 both have updated_at, defined differently, and the plan does not say which to use. Yours to decide.`
- Bad: `Ran into a problem`

更多内容见无人值守:什么时候必须停。