8.1
A knowledge base: an honest index of the code知識庫:程式碼的誠實索引知识库:代码的诚实索引
This chapter is the first of a case study. It assumes you have read Context budget and What an agent should remember, which give the general ideas. It fits a team with a large, old code base. If your code base is small, read it to decide that you do not need this. The most useful part is the small experiment in Test your own setup: you can run it before you build anything.
這一章是個案研究的第一章。讀它,你需要讀過 上下文是一份預算 和 agent 該記住什麼,它們講的是一般的想法。它適合有一大份老程式碼的團隊。如果你的程式碼很小,讀它是為了判斷你不需要。最有用的部分,是 測你自己的設定 裡那個小實驗:你在建任何東西之前,就可以先跑。
这一章是案例研究的第一章。读它之前,你需要读过上下文是一份预算和agent 该记住什么,它们讲的是一般的思路。它适合有一大份老代码的团队。如果你的代码很小,读它是为了判断自己不需要。最有用的部分,是在你自己的环境里测一测里那个小实验:什么都还没建,你就可以先跑。
The Knowledge經驗分享经验分享
In one sentence
The code is the truth. A knowledge base is only an index and summary of it, which should be cheaper to read. It does not try to be complete on day one. It tries to be honest: each card says which version of the source file it read, and each gap is written down where the next reader will see it.
一句話
程式碼才是真相。知識庫只是它的索引和摘要,讀起來應該比較便宜。它不求第一天就完整,它求誠實:每張卡片說明它讀的是哪個版本的原始檔案,每個缺口都寫在下一個讀者會看到的地方。
一句话
代码才是真相。知识库只是它的索引和摘要,读起来应该更便宜。它不求第一天就完整,只求诚实:每张卡片都写明它读的是源文件的哪个版本,每个缺口都写在下一个读者看得到的地方。
For leaders
- The decision: whether to fund a knowledge base (a folder of short notes about the code, written for agents), and who will own it. Test first whether searching the code is already enough.
- The risk: searching starts to hurt when the code base is large, the same exploration is paid for in every session, or a wrong answer is expensive. I have not measured a knowledge base against plain search, so this is a bet, not a proven win. A base nobody refreshes becomes confidently wrong.
- The cost of doing it right: the model reads each object's code once; for a large domain that is real money, and I have not priced it. Someone must own the refresh, and the notes need the same access rules as the code.
- Ask the team: "On ten questions we know the answers to, how often does an agent with plain search get it right?"
給主管
- 要做的決定:要不要出錢做知識庫(一個資料夾,裡面是寫給 agent 的程式碼短筆記),以及誰負責。先測一下,只搜尋程式碼是不是已經夠了。
- 風險:程式碼庫很大、同樣的探索在每個會話都要再付一次、或者答錯很貴的時候,搜尋就開始吃力。我沒有拿知識庫和單純搜尋比較過,所以這是一場賭注,不是證明過的勝利。沒有人更新的知識庫,會變成很有自信地答錯。
- 做對的成本:模型把每個物件的程式碼讀一遍;對大的領域,這是真金白銀,我沒有算過價。要有人負責更新,筆記也需要和程式碼一樣的存取規則。
- 可以問團隊:「十個我們知道答案的問題,只用單純搜尋的 agent 答對幾個?」
写给管理者
- 要拍板的事:要不要出钱做知识库(一个文件夹,里面是写给 agent 看的代码短笔记),以及由谁负责。先测一下,只搜索代码是不是已经够用。
- 风险:代码库很大、同样的探索每个会话都要再付一次、或者答错代价很高的时候,搜索就开始吃力。我没有拿知识库和单纯搜索比过,所以这是一次押注,不是已经证明的收益。没人更新的知识库,会变得自信满满地答错。
- 做对的代价:模型要把每个对象的代码读一遍;对大的领域,这是真金白银,我没有算过价。要有人负责更新,笔记也需要和代码一样的访问规则。
- 可以问团队:“十个我们知道答案的问题,只用单纯搜索的 agent 能答对几个?”
The problem
Say a team owns a code base with a few thousand objects. An object is a named thing in the code that other things use: a stored procedure, a scheduled job, a class, a table. You ask an agent to change one of them. To do it safely, the agent has to know what the object does, who uses it, and what breaks if it changes.
A new agent session starts knowing none of this. The first question is the obvious one.
Why not just let the agent search the code?
An agent can search. It can run grep (find every line that contains a word), open files, and follow names. For many jobs that is the right answer, and it costs nothing to set up. I want to say clearly when it is enough. Searching also does not have to be bare grep: a language server (the editor service that answers "where is this defined, who uses it") or a code-search service can help, and a short, good rules page helps too. The knowledge base has to beat that combination, not bare grep.
Searching is enough when:
- The code base is small, or the part you need fits in one context.
- You know the name of what you are looking for.
- The task is a one-off, so nobody pays for the same exploration twice.
It starts to hurt when:
- The agent decides what to read next from what it just read. It can miss an object, follow a name that means something else, and stop too early. It cannot tell you how much it missed. Ask it twice and you may get two different answers.
- The same exploration is paid for in every session. Every new session starts with an empty context (context budget), so the agent finds the same things again.
- Some things are not in the code. Which environment runs a job, why a rule exists, what failed last year. No search finds them, because they are not written there.
- A wrong answer is expensive. If the object touches shared data, a guess from a partial search is not good enough.
A knowledge base is a folder of plain text files about the code, written for agents to read. The idea is to pay once for the exploration, keep the result, and read the result first because it should be cheaper than the code. I have not measured that.
I have not measured it against searching. I have not run the same questions once with plain search and once with a knowledge base, and I do not know by how much the second one wins, if it does. What I have is the reasoning above, and a way for you to test it on your own code (see Test your own setup). Treat the knowledge base as a bet that pays off under the conditions above, not as a proven win.
問題
假設一個團隊擁有一份有幾千個物件的程式碼庫。物件是程式碼裡一個有名字、被別的東西使用的東西:預存程序、排程工作、類別、資料表。你請 agent 改其中一個。要改得安全,agent 得知道這個物件做什麼、誰在用它、改了會壞掉什麼。
新的 agent 會話開始時,這些一概不知道。第一個問題是顯而易見的。
為什麼不乾脆讓 agent 搜尋程式碼?
agent 會搜尋。它能執行 grep(找出每一行含有某個詞的地方)、開檔案、順著名字追。對很多工作,這就是正確的答案,而且不用任何設定。我想說清楚它什麼時候就夠了。搜尋也不必是單純的 grep:語言伺服器(回答「這個在哪裡定義、誰在用」的編輯器服務)或程式碼搜尋服務都可以幫忙,一頁簡短而好的規則也有幫助。知識庫要贏的是這一整套,不是單純的 grep。
搜尋就夠的時候:
- 程式碼庫很小,或者你要的那一塊放得進一個上下文。
- 你知道要找的東西的名字。
- 任務只做一次,所以沒有人為同樣的探索付兩次。
開始吃力的時候:
- agent 靠剛讀到的東西,決定下一步讀什麼。它可能漏掉一個物件,追到一個名字相同、意思不同的東西,太早停下來。它說不出自己漏了多少。問它兩次,可能得到兩個不同的答案。
- 同樣的探索,每個會話都要付一次。每個新會話都從空的上下文開始(上下文預算),所以 agent 又找到同樣的東西。
- 有些事不在程式碼裡。哪個環境執行一個工作、一條規則為什麼存在、去年什麼壞了。搜尋找不到,因為那裡沒有寫。
- 答錯很貴。如果物件碰到共用的資料,靠不完整的搜尋猜出來的答案,是不夠的。
知識庫是一個資料夾,裡面是關於程式碼的純文字檔案,寫給 agent 讀。想法是:探索只付一次錢,把結果留下來,並先讀結果,因為它應該比讀程式碼便宜。這一點我沒有量過。
我沒有拿它和搜尋比較過。我沒有把同樣的問題,一次用單純搜尋、一次用知識庫跑過,所以我不知道第二個贏多少,甚至贏不贏。我有的,是上面的推理,以及一個讓你在自己的程式碼上測試的辦法(見 測你自己的設定)。把知識庫看成一場賭注:在上面那些條件下才會有回報,不是證明過的勝利。
问题
假设一个团队有一份几千个对象的代码库。对象是代码里有名字、被别的东西使用的东西:存储过程、定时任务、类、表。你让 agent 改其中一个。要改得安全,agent 得知道这个对象是干什么的、谁在用它、改了会弄坏什么。
新开的 agent 会话,这些一概不知道。第一个问题显而易见。
为什么不直接让 agent 搜索代码?
agent 会搜索。它能运行 grep(找出每一行含有某个词的地方)、打开文件、顺着名字追。很多活这就是正确答案,而且不用任何配置。我想先说清楚它什么时候就够了。搜索也不必是单纯的 grep:语言服务器(回答“这个在哪里定义、谁在用”的编辑器服务)或代码搜索服务都能帮忙,一页简短而好的规则也有用。知识库要赢的是这一整套,不是单纯的 grep。
搜索就够的时候:
- 代码库很小,或者你要的那一块装得进一个上下文。
- 你知道要找的东西叫什么。
- 任务只做一次,没人会为同样的探索付两次钱。
开始吃力的时候:
- agent 根据刚读到的东西,决定下一步读什么。它可能漏掉一个对象,追到一个重名但意思不同的东西,太早停下来。它说不出自己漏了多少。问它两次,可能得到两个不同的答案。
- 同样的探索,每个会话都要付一次。每个新会话都从空的上下文开始(上下文是一份预算),所以 agent 又会把同样的东西找一遍。
- 有些事不在代码里。哪个环境运行某个任务、某条规则为什么存在、去年出了什么故障。搜索找不到,因为那里没写。
- 答错代价很高。如果对象碰到共用的数据,靠不完整的搜索猜出来的答案是不够的。
知识库是一个文件夹,里面是关于代码的纯文本文件,写给 agent 读。思路是:探索只付一次钱,把结果留下来,并且先读结果,因为它应该比读代码便宜。这一点我没有量过。
我没有拿它和搜索比较过。我没有把同样的问题,一次用单纯搜索、一次用知识库跑过,所以我不知道第二种赢多少,甚至赢不赢。我有的,是上面的推理,以及一个让你在自己的代码上测试的办法(见在你自己的环境里测一测)。把知识库看成一次押注:满足上面那些条件才会有回报,不是已经证明的收益。
How it works
The shape of a knowledge base
A reader goes down only as far as the task needs.
- The overview lists the domains and has a glossary. A domain is a group of objects that serve one job, such as "orders" or "payroll".
- The architecture page of a domain says what the domain is for, its main flows, where to start reading, its traps and its limits.
- A card is a short entry about one object: what it is for, its rules, who it uses, its traps. Each rule cites the lines of code it comes from. One file holds the cards of one type. An agent finds a card by walking down: overview, then the domain's page, then the card by its id.
- The code is at the bottom. It is the source of truth. If a card and the code disagree, the code wins.
So a card is a promise with a date, not a replacement for the code. An agent that needs more reads the code.
Scripts do the structure, the model does the meaning
Two kinds of work go into a card, and they are different.
- Structure has one right answer: which objects exist, who uses whom (together, the map of the code), in what order to learn them, whether a card lists the right relations. A script can compute this. It gives the same answer every time and costs no tokens. A model asked to do it walks the code by judgment, and may miss things.
- Meaning has no single answer: what an object is for, what its rule is, which trap catches people. Only a model, reading the code, can write it.
The rest of this part follows from that split. The toolkit is how scripts draw the map. The audit measures that map. Learning in batches is where the model writes the meaning, with scripts checking what they can. Keeping it true is what happens after the code changes.
Honest, not complete
My guess is that most of a base can come from the code. That is a guess, not a measurement. The rest cannot: what runs in which environment, what failed and why, what someone decided. That part comes over time, from finished tasks, from root-cause reports, from what people export. So the base is never finished on day one, and pretending it is would make it worse, because a base that looks complete gets believed.
Two habits keep it honest:
- Every card says which version of its source file it read. It records a commit (a saved version of the code, named by a short id called a sha). The scripts also keep an object index: a list of every object, the source file it lives in, and that file's sha. That is how you can later list the cards the code has moved past. Chapter 8.5 shows how.
- Every gap is written down. What the code cannot tell goes into a requests list: one row per thing a person must give, with the kind of thing it is and a read-only way to get it. The agent asks for these at its next stop, never in the middle of work. Chapter 8.5 has the details.
Every step is a task a person approves
Building the base is not one big prompt. Each step is a task (see Manage tasks, not chats) with a plan the person approves and a write-back the person approves (the write-back copies the finished work into the base; see Two gates: where a person approves). Scripts check what can be checked: the form of the files, the relations, the cited lines. And I do not let the agent connect to a live environment. What only an environment can tell, a person runs and hands over.
The road
- Build a toolkit, once per code base (8.2).
- Compute the map, before each use (8.2).
- Audit the map (8.3).
- Split the code into domains, once (8.4).
- Learn each domain in batches (8.4).
- Write the architecture page (8.4).
- Keep it true: refresh, capture, requests (8.5).
Test your own setup {#test}
Before you build anything, find out whether you need it.
- Write 10 questions about your code whose right answers you know. Mix kinds: "what calls X?", "what happens if Y changes?", "why does Z skip this case?".
- Ask an agent each question in a fresh chat, with plain search only. Score each answer right or wrong against what you know.
- Write cards for one small domain by hand or with the agent. Ask the same questions again with the cards available, in fresh chats.
- Compare: right answers, usage (the token numbers your tool shows for a run), time.
Two cautions. Ask the questions in a form that cannot be answered from one file, such as "what breaks if Y changes?", and let someone who has not read the cards choose them. Ten questions can only show a large difference.
Do each condition several times, not once, because an agent does not do the same thing twice (see Variance). If search alone scores about the same, do not build the base.
原理
知識庫的形狀
讀者只往下走到任務需要的深度。
- 總覽列出領域,並有一份詞彙表。領域是為了同一件工作的一組物件,例如「訂單」或「薪資」。
- 一個領域的架構頁說明這個領域是做什麼的、主要的流程、從哪裡開始讀、它的陷阱和它的限制。
- 卡片是關於一個物件的短條目:它做什麼、它的規則、它用誰、它的陷阱。每條規則都註明它來自哪幾行程式碼。一個檔案放同一種類型的卡片。agent 往下走來找到卡片:總覽,然後是領域的頁面,再用 id 找到卡片。
- 程式碼在最底下。它是真相的來源。卡片和程式碼不一致時,程式碼贏。
所以卡片是一份附日期的承諾,不是程式碼的替代品。需要更多的 agent,去讀程式碼。
腳本做結構,模型做意義
寫一張卡片有兩種工作,它們不一樣。
- 結構有一個正確答案:有哪些物件、誰用誰(合起來是程式碼的地圖)、照什麼順序學它們、一張卡片列的關係對不對。腳本能算出來。每次答案都一樣,也不花 token。要模型去做,它是憑判斷在程式碼裡走,可能漏掉東西。
- 意義沒有單一答案:一個物件是做什麼的、它的規則是什麼、哪個陷阱會絆住人。只有讀了程式碼的模型能寫。
這一部其餘的內容,都從這個分工來。Toolkit 是腳本怎麼畫出地圖。盲抽查 量這張地圖。分批學 是模型寫下意義的地方,腳本能檢查的就檢查。讓它一直是對的 是程式碼改了之後的事。
誠實,不求完整
我的猜測是,知識庫的大部分可以從程式碼來。這是猜測,不是量測。其餘的不行:什麼在哪個環境執行、什麼壞了和為什麼、有人做了什麼決定。這一部分隨時間而來,來自做完的任務、根因報告、人們匯出的東西。所以知識庫第一天不會完成,假裝完成只會讓它更糟,因為看起來完整的知識庫,會被人相信。
兩個習慣讓它誠實:
- 每張卡片說明它讀的是它的原始檔案的哪個版本。它記下一個 commit(程式碼的一個存下來的版本,用一個叫 sha 的短 id 命名)。腳本也維護一份物件索引:每個物件的清單、它所在的原始檔案,以及該檔案的 sha。這樣你之後才能列出程式碼已經走過去的卡片。第 8.5 章 說明怎麼做。
- 每個缺口都寫下來。程式碼說不出的,進入一份請求清單:每一列是一件必須由人提供的事,附上它是哪一種,以及一個唯讀的取得辦法。agent 在下一個停下來的地方問這些,從不在工作到一半時問。第 8.5 章 有細節。
每一步都是一個由人批准的任務
建知識庫不是一個大 prompt。每一步都是一個任務(見 管任務,不管對話),有一份人批准的計劃,和一次人批准的寫回(寫回是把做完的工作複製進知識庫;見 兩道門:人在哪裡批准)。腳本檢查能檢查的:檔案的格式、關係、被引用的行。而且我不讓 agent 連上正在執行的環境。只有環境才說得出的事,由人執行並交過來。
路線
- 建一個 toolkit,每個程式碼庫一次(8.2)。
- 計算地圖,每次使用之前(8.2)。
- 抽查地圖(8.3)。
- 把程式碼分成領域,一次(8.4)。
- 分批學每個領域(8.4)。
- 寫架構頁(8.4)。
- 讓它一直是對的:更新、擷取、請求(8.5)。
測你自己的設定 {#test}
在你建任何東西之前,先弄清楚你需不需要它。
- 寫 10 個關於你程式碼的問題,正確答案是你知道的。混合幾種:「什麼呼叫 X?」、「Y 改了會怎樣?」、「為什麼 Z 跳過這個情況?」
- 在全新的對話裡,只用單純搜尋,把每個問題問 agent。照你知道的,每個答案判對或錯。
- 為一個小領域寫卡片,自己寫或讓 agent 寫。在全新的對話裡,有卡片可用的情況下,再問同樣的問題。
- 比較:答對的數量、用量(你的工具為一次運行顯示的 token 數字)、時間。
兩個提醒。問題的形式要讓人無法只靠一個檔案回答,例如「Y 改了會壞掉什麼?」,並讓沒讀過卡片的人來選。十個問題只看得出很大的差別。
每個條件都做好幾次,不要只做一次,因為 agent 不會做兩次同樣的事(見 一次運行證明不了什麼)。如果單靠搜尋得分差不多,就不要建知識庫。
原理
知识库的形状
读者只往下走到任务需要的深度。
- 总览列出领域,并有一份词汇表。领域是为同一项工作服务的一组对象,例如“订单”或“薪资”。
- 一个领域的架构页写明这个领域是干什么的、主要的流程、从哪里开始读、它的坑和它的限制。
- 卡片是关于一个对象的简短条目:它的用途、它的规则、它用到谁、它的坑。每条规则都引用它所依据的代码行。一个文件放一种类型的卡片。agent 顺着往下走来找卡片:总览,再到领域的页面,再按 id 找到卡片。
- 代码在最底下。它是真相的来源。卡片和代码不一致时,以代码为准。
所以卡片是一份带日期的承诺,不是代码的替代品。agent 需要更多时,就去读代码。
脚本管结构,模型管含义
写一张卡片有两种活,它们不一样。
- 结构只有一个正确答案:有哪些对象、谁用谁(合起来就是代码的地图)、按什么顺序去学、一张卡片列出的关系对不对。脚本能算出来。它每次给同样的答案,也不花 token。让模型来做,它会凭判断在代码里走,可能漏东西。
- 含义没有唯一的答案:一个对象是干什么的、它的规则是什么、哪个坑会绊倒人。只有模型读了代码才写得出来。
这一部分后面的内容都由这个分工推出来。toolkit讲脚本怎么画地图。审计衡量这张地图。分批学一个领域是模型写下含义的地方,脚本检查它能检查的部分。让知识库一直是对的讲代码改了以后怎么办。
求诚实,不求完整
我的猜测是,知识库的大部分内容可以从代码里得到。这是猜测,不是测量。其余的得不到:什么在哪个环境里运行、出过什么故障、原因是什么、谁做了什么决定。这部分要靠时间积累,来自做完的任务、根因报告、人导出的东西。所以知识库第一天不可能完成;假装它完成了只会更糟,因为一个看起来完整的知识库会被人相信。
两个习惯让它保持诚实:
- 每张卡片都写明它读的是源文件的哪个版本。它记录一个 commit(代码的一个已保存版本,用一个叫 sha 的短 id 命名)。脚本还维护一份对象索引:每个对象一行,写明它在哪个源文件里,以及那个文件的 sha。这样你以后就能列出代码已经改过、卡片还没跟上的那些卡片。第 8.5 章讲怎么做。
- 每个缺口都写下来。代码说不清的事,进入一张请求清单:每件需要人提供的东西一行,写明它是哪一类,以及一种只读的获取办法。agent 在下一个停靠点提出这些请求,绝不在干活到一半时提。第 8.5 章有细节。
每一步都是一个由人审批的任务
建知识库不是一个大 prompt。每一步都是一个任务(见管任务,不管对话),计划由人审批,写回也由人审批(写回是把做完的工作复制进知识库;见两道门:人在哪里审批)。脚本检查能检查的部分:文件的格式、关系、引用的行。我也不让 agent 连接线上环境。只有环境才知道的事,由人去运行、再交给它。
路线
- 搭一个 toolkit,每个代码库一次(8.2)。
- 计算地图,每次使用之前(8.2)。
- 审计地图(8.3)。
- 把代码切成领域,一次(8.4)。
- 分批学每个领域(8.4)。
- 写架构页(8.4)。
- 让它一直是对的:更新、捕获、请求(8.5)。
在你自己的环境里测一测 {#test}
在建任何东西之前,先弄清楚你需不需要它。
- 写 10 个关于你的代码的问题,正确答案你是知道的。种类要混着来:“什么调用了 X?”“如果 Y 改了会怎样?”“为什么 Z 跳过了这种情况?”
- 每个问题在新对话里问 agent,只用单纯搜索。对照你已知的答案,每个回答判对或错。
- 手工或让 agent 帮忙,给一个小领域写卡片。有了卡片,在新对话里再问同样的问题。
- 比较:答对的个数、用量(你的工具为一次运行显示的 token 数)、时间。
两点提醒。提问的形式要让一个文件回答不了,比如“如果 Y 改了,什么会坏?”,而且让没读过卡片的人来选题。十个问题只能显示出很大的差别。
每种条件都要做几次,不要只做一次,因为 agent 不会把同一件事做两次一样(见一次运行证明不了什么)。如果只靠搜索得分差不多,就不要建知识库。
Costs and traps
- It needs upkeep. A base nobody refreshes becomes confidently wrong. If your code changes daily and nobody will own the refresh, search is the better choice.
- A card can be wrong. It is a model's reading of the code. The checks catch the structure, not whether a rule is understood right. A person's review, or an independent reviewer (a model checking a model), has to cover that.
- A card can anchor the agent. An agent that reads a card first may look at less code and keep a wrong card's view. For work where a mistake is expensive, have it re-read the lines a card cites.
- Reading cards costs tokens too. A base that is too long only moves the cost. Cards should be short, and the agent should open the lower layers only when it needs them.
- Building has a price. The model reads each object's code once. For a large domain that is real money. It is a bet that the reading will be reused. A rough size: every object read once, plus the files that change each month. I have not priced it. Prompt caching (Anthropic's docs say a cached read costs about a tenth of the base price; I have not checked this on Copilot; see Choosing a model) may lower both the building and the reading, so test with it on, as you would really run.
- Someone must own it, and the cards need the same access rules as the code. A card is a summary of internal code. Decide who refreshes it and who may read it, the same way you do for the code.
代價和陷阱
- 它需要維護。沒有人更新的知識庫,會變成很有自信地答錯。如果你的程式碼每天都在變,又沒有人負責更新,搜尋是比較好的選擇。
- 卡片可能是錯的。它是模型對程式碼的解讀。檢查抓得到結構,抓不到一條規則是不是理解對了。這要靠人的審查,或獨立的 reviewer(模型能檢查模型嗎)來涵蓋。
- 卡片可能讓 agent 被錨定。先讀卡片的 agent,可能看比較少的程式碼,並保留錯誤卡片的看法。對答錯很貴的工作,讓它重讀卡片引用的那幾行。
- 讀卡片也花 token。太長的知識庫只是把成本搬到別處。卡片要短,agent 只在需要時才打開下面的層。
- 建它是有價錢的。模型把每個物件的程式碼讀一遍。對大的領域,這是真金白銀。這是賭讀過的東西會被重複使用。粗略的大小:每個物件讀一遍,加上每個月會變的檔案。我沒有算過價。prompt 快取(Anthropic 的文件說,快取讀取大約是基本價格的十分之一;我沒有在 Copilot 上確認過;見 選模型:算的是每次成功的成本)可能同時降低建和讀的成本,所以測的時候要開著它,像你真正執行時那樣。
- 必須有人負責,而且卡片需要和程式碼一樣的存取規則。卡片是內部程式碼的摘要。決定誰更新它、誰可以讀它,像你對程式碼做的那樣。
代价和坑
- 它需要维护。没人更新的知识库,会变得自信满满地答错。如果你的代码天天在变、又没人负责更新,搜索是更好的选择。
- 卡片可能是错的。它是模型对代码的理解。检查只能抓住结构,抓不住一条规则理解得对不对。这部分要靠人审查,或者靠独立的 reviewer(模型能检查模型吗)。
- 卡片可能把 agent 锚住。先读卡片的 agent,可能少看一些代码,还沿用一张错卡片的看法。对出错代价高的工作,让它重读卡片引用的那几行。
- 读卡片也要花 token。太长的知识库只是把成本挪了个地方。卡片要短,agent 只在需要时才往下打开更低的层。
- 建知识库有成本。模型要把每个对象的代码读一遍。对大的领域,这是真金白银。这是押注读的结果会被反复用到。粗略的规模:每个对象读一遍,加上每月变动的文件。我没有算过价。prompt 缓存(Anthropic 的文档说缓存读取约为基础价格的十分之一;我没有在 Copilot 上核实过;见选模型:看每次成功的成本)也许能同时降低建库和读取的成本,所以测试时要打开它,就像你真正运行时那样。
- 要有人负责,卡片需要和代码一样的访问规则。卡片是对内部代码的摘要。像对代码一样,决定谁来更新、谁能读。
When to delete it
If your own test shows that search alone gives the same answers at the same cost, delete the cards and keep only the requests list, because that is the part search can never give. And if the platform one day builds and refreshes a code index that you can measure as accurate, use it instead of keeping your own.
什麼時候可以刪掉
如果你自己的測試顯示,單靠搜尋,用同樣的成本給出同樣的答案,就把卡片刪掉,只留請求清單,因為那是搜尋永遠給不了的部分。還有,如果有一天平台建立並更新一份程式碼索引,而且你量得出它是準確的,就用它,不要自己維護。
什么时候可以删掉
如果你自己的测试表明,只靠搜索就能以同样的成本给出同样的答案,就把卡片删掉,只留下请求清单,因为这是搜索永远给不了的部分。如果哪天平台能构建并更新一份代码索引,而且你测得出它是准确的,就用它,别再自己维护一份。
Try it on your own setup
No harness needed. Open your agent in your own repository and paste:
Judge whether this repository would gain from a written knowledge base of the code, or whether search is enough. Estimate how many objects it has (modules, jobs, tables, services) and how large the code base is. Name the kinds of facts that are not in the code at all, such as which environment runs a job or why a rule exists. Say how often the code changes. Then give a verdict: search is enough, or a base is worth testing, with the reasons. Do not change any files.在你自己的環境試試
不用裝 harness。在你自己的倉庫裡打開 agent,貼上:
判斷這個倉庫是否會從一份寫下來的程式碼知識庫得到好處,還是搜尋就夠了。估計它有多少物件(模組、工作、資料表、服務),以及程式碼庫有多大。指出完全不在程式碼裡的那幾類事實,例如哪個環境執行一個工作,或一條規則為什麼存在。說明程式碼多久變一次。然後給出結論:搜尋就夠,或值得測一個知識庫,並附上理由。不要改任何檔案。在你自己的环境里试试
不用装 harness。在你自己的仓库里打开 agent,粘贴:
判断这个仓库是否能从一份写下来的代码知识库中受益,还是搜索就够了。估算它有多少个对象(模块、任务、表、服务),代码库有多大。指出哪些种类的事实根本不在代码里,比如哪个环境运行某个任务、某条规则为什么存在。说明代码多久变动一次。然后给出结论:搜索就够,或者值得测试一份知识库,并给出理由。不要修改任何文件。Go deeper
- Context budget: why reading less matters, and the search-or-map choice in general.
- What an agent should remember: memory in general; a knowledge base is one kind.
- The toolkit, the first step of the road.
延伸閱讀
- 上下文是一份預算:為什麼少讀很重要,以及一般來說,搜尋還是地圖的選擇。
- agent 該記住什麼:一般的記憶;知識庫是其中一種。
- Toolkit:用腳本畫出程式碼的地圖,路線的第一步。
延伸阅读
- 上下文是一份预算:为什么少读很重要,以及一般意义上“搜索还是地图”的选择。
- agent 该记住什么:记忆的一般情况;知识库是其中一种。
- toolkit,路线的第一步。
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
Copilot Harness builds a knowledge base from code with the road above. It can teach you how from the inside, with the real files and commands. After the setup above, type:
/harness-rookie-wondering I have read the chapter "A knowledge base: an honest index of the code". Teach me topic 16, the knowledge base from code. Open the real skills and files with me, show me the road step by step, and draw how the pieces fit together.It teaches one small piece at a time, stops to ask if you are following, and opens the files with you.
在 harness 裡探索
Copilot Harness 用上面的路線,從程式碼建一個知識庫。它可以從裡面教你怎麼做,用真實的檔案和指令。照上面的說明準備好之後,輸入:
/harness-rookie-wondering 我讀完了「知識庫:程式碼的誠實索引」這一章。請教我主題 16,從程式碼建知識庫。和我一起打開真實的 skill 和檔案,一步一步讓我看這條路線,並畫出各個部分怎麼組合在一起。它一次教一小塊,停下來確認你跟得上,然後和你一起打開檔案。
在 harness 里探索
Copilot Harness 就是按上面的路线,从代码建出知识库的。它可以从内部教你怎么做,配上真实的文件和命令。按上面的说明准备好之后,输入:
/harness-rookie-wondering 我读完了“知识库:代码的诚实索引”这一章。请教我主题 16,从代码建知识库。带我打开真实的 skill 和文件,一步一步给我看这条路线,并画出各部分是怎么连起来的。它一次只教一小块,停下来确认你跟上了,再和你一起打开文件。