AI 協作開發：Context 節流與錨點術

解決問題：當專案文件與規範體積過大時，AI 協作開發常因讀取過多無關資訊而消耗大量記憶體，進而產生注意力分散與推理能力下降的問題。適合誰讀：正在使用 AI Coding Agent，這是一種自動化開發代理工具，進行中大型專案開發，且對 grep 指令與專案文件結構管理有基礎認識的開發者。讀完能做到什麼：掌握「任務錨點」、「決策目錄」與「索引化 SSoT」等重構技術，將千行文件改造成 AI 每次僅需精準讀取 1K token 的高效結構，並學會如何透過外包機制維護主 AI 的專注度。

這是一篇記錄 2026 年 7 月實戰經驗的技術筆記。這套流程之後仍在持續演進，本文未回頭逐條更新，所有數據與條款均停留在當時的時間點。

為什麼 AI 讀完規範就變笨了？量化痛點分析

在開發 Nailora，這是一個美甲情報 App 專案，的過程中，文件庫隨著功能疊加快速膨脹。當時的路線圖累積超過 1000 行、包含 223 個待辦任務；決策記錄檔超過 900 行、記載了 370 多條技術決策；此外還有 11 個共用規範的子檔案。

當專案成長至此，我透過一次 harness，這是指由這套規則、Agent（智慧代理）與 Skill（技能）共同組成的開發框架本身，的自我審計實測發現：主 AI 在任務啟動階段會自動讀取所有規範。這導致單次任務光是讀取規範就消耗約 69K token，直接佔用 200K token 上下文記憶體視窗的 35%。

然而，該次任務實際僅涉及 3 到 5 條規則。記憶體被無關資訊填滿會導致 AI 降智且注意力分散。為了保持 AI 敏銳度，我必須限制它只讀取當下所需的行數。

graph TD
    A[開發任務啟動] --> B[主 AI]
    B -->|1. 查詢任務| C[路線圖檔]
    C -->|grep 精準撈取| D[任務錨點]
    B -->|2. 鎖定決策| E[決策記錄檔]
    E -->|ToC 檢索| F[決策目錄]
    F -->|grep 撈取前後五行| G[決策本體]
    B -->|3. 讀取規範| H[路標檔]
    H -->|索引導向| I[11個主題子檔]
    J[Plan-Reviewer 外包 AI] -->|全檔審查| K[防漏閘門]
    K -->|僅輸出結論| B

錨點術三件套：如何讓 AI 精準讀取？

我開發了「錨點術三件套」，透過結構調整強迫 AI 精準讀取，解決暴飲暴食 token 的問題。

1. 任務錨點

錨點是埋在檔案中、可被 grep，這是一個文本搜尋工具，精準定位的固定標籤。在路線圖檔案中，我在每個任務上方埋入一行 HTML 註解，格式如 。

當 AI 需要讀取任務資訊時，我限制它使用 grep -A 10 指令僅撈取該錨點後十行的內容，禁止開啟整份文件。若錨點未命中，AI 禁止退回讀取全檔，必須立刻回報失效。

2. 決策記錄雙區結構

決策記錄檔採用「雙區結構」設計。頂部為一行一條的目錄（含決策編號與摘要），下方為詳細的決策表格。

AI 讀取流程分為兩步：首先僅讀取目錄區，鎖定相關決策編號；接著用 grep 搜尋編號，僅撈取該表格區塊前後五行，禁止讀取全檔。決策記錄遵循「不刪除、只疊加」原則，被推翻的決策僅用刪除線標記並加上新版本號，保留歷史脈絡。

3. 索引化 SSoT 結構

共用規範採取「路標檔 + 本體子檔」兩層架構。路標檔作為索引，僅存放「關鍵字 → 子檔路徑」的導航與載入規則。規範本體拆分為 11 個主題子檔（如色彩、字型、間距等）。

每個子檔頂部放有唯一真相源，這是一種確保系統中特定資訊僅存在於單一地方的設計，宣告。該宣告明確指出：禁止在專案其他地方複述條款本體，所有引用必須指向此處，防止規則版本混亂。

技術細節：精準撈取指令與結構範例
這裡展示如何透過 grep 指令實現局部讀取，避免載入完整檔案：

任務錨點撈取範例：
grep -A 10 "" roadmap.md
決策記錄檔結構示意：
# 決策記錄
## 目錄區
- ADR-001: 採用 SQLite 作為本機快取
- ADR-002: 統一使用 Tailwind CSS 間距規範
 
## 內容區

| 編號 | 決策 | 狀態 | 來源任務 |
| ADR-001 | 採用 SQLite | 已驗證 | [[Nailora 美甲情報 App 複盤]] |
AI 會先讀取「目錄區」，得到 ADR-001 後，再用 grep -A 5 "" 僅讀取該決策細節。

全檔閱讀的正確姿勢：外包給專屬 Agent

若任務需要「全檔視野」（如確認新計畫是否遺漏既有決策），我不對主 AI 開放全檔權限，而是將其外包。我引入 plan-reviewer，這是一個獨立且專門負責方案審查的 AI 代理，。我要求它讀取全檔，作為主 AI 精準讀取防線之外的抗失效閘門。

主 AI 僅接收 plan-reviewer 的審查結論。因為主對話的 context 最稀缺，而外包 agent 的 context 屬於一次性消耗，用完即丟。

這種瘦身哲學也應用在根目錄的 CLAUDE.md，這是一個用於引導 AI 快速融入專案規範的指導檔，。我將其壓縮在 60 餘行內，僅保留高頻開發紅線，其餘細節表格化並指示 AI 按需查閱。撰寫原則遵循 Anthropic 官方建議：逐行檢視，只要「刪了不出錯」就一律剔除，避免過長檔案被模型忽略。

跨會話交棒的診斷閘門

跨多個 session，即 AI 的單次對話會話，進行長週期開發時，需依靠交棒文件，這是在會話切換時用來傳遞上下文狀態的記錄檔，。

前一個 session 記錄的「問題根因是 X」往往只是直覺假設。若下個 session 直接照單全收，容易往錯誤方向偏航，耗費 token。

為此，我要求所有交棒文件必須在 frontmatter，即檔案頂部的元數據區塊，中標注診斷狀態與驗證方式：

診斷狀態: 假設 / 已驗證 / 已證偽
驗證方式: 實機 / 型別檢查 / grep / 無

並執行以下規則：

僅「已驗證」的結論能直接納入執行計畫。
狀態為「假設」的結論，在未完成驗證前，禁止產出任何修改程式碼的方案。
「已證偽」的交棒文件，在收尾時必須重命名並加上 deprecated（已廢棄）標記，並在文件頂部加上警告。

此外，一旦主對話 context 消耗超過 15%，就必須強制切換到全新 session 並產出交棒文件，以維持 AI 推理品質。

自我審計：防止規則無限膨脹

為了防止規範無限制擴張，我為開發框架設計了三道防線：

錨點顯性化：新增規範時必須掛載實際發生過的具體問題編號（如 bug 編號或決策編號）。無錨點的純預防性規則一律禁止寫入，避免「以防萬一」造成膨脹。
事件記錄：所有 TRIVIAL 任務，即微不足道的輕微改動，與 hotfix bypass（緊急熱修復跳過規範）等例外事件，必須記錄至 events.jsonl。我會定期審查，將觸發率為零的規則 sunset（逐步淘汰）。
健康度檢查：使用腳本定期量測指導檔、skills（AI 的技能集）與決策記錄目錄的同步度。檢查結果呈現純文字的紅燈、黃燈、綠燈狀態。若為紅燈，收尾流程強制中止。

技術細節：同步度檢查腳本原理

該腳本（尚未在本文中提供完整程式碼，僅說明邏輯）會在每次 git commit 前自動運行。它會比對：

CLAUDE.md 中引用的子規範檔案路徑是否存在。

events.jsonl 中是否有未關聯決策編號的例外記錄。

確保所有的決策目錄編號，皆能在下方的表格區中找到對應的  錨點。任何一項檢查未通過，腳本即輸出「狀態：紅燈」並中斷流程。

業界實踐對照

業界共識指出：Agent 本質上是無狀態的，每次會話需讀取並推導 5K 到 20K token。開發瓶頸在於「缺乏記憶的組織方式」，而非模型推理能力。

主流做法是將記憶當作「檔案系統」分層管理，這與 Nailora 的「路標檔 + 本體子檔」結構一致。

此外，傳統 ADR，即架構決策記錄，正延伸出 AgDR，即代理決策記錄，的概念。AI 做的技術選擇同樣需要可稽核性，並由 Agent 主動建檔。

在 Nailora 專案中，我更進一步將每條記錄編碼其「來源任務」，完整還原流程軌跡（包括通過的驗證閘門與結果），提供強力的技術佐證。

待辦 / 疑問

待辦：目前決策記錄已超過 900 行，ToC + grep 模式的極限規模在哪裡、何時需要進行拆檔，此部分目前尚未驗證。

Jun 的學習筆記

探索