前言¶

方案討論裏常見兩種失效方式：口頭對齊很快，事後各執一詞；或者一上來就寫長篇設計文檔，細節還沒問清就固化了錯誤假設。更穩妥的做法是把「拷問式訪談」和「可版本化的文檔」綁在一起：每澄清一個概念就寫進術語表，真正值得留痕的取捨才落成 ADR。

下面介紹 SkillHub 上的 grill-with-docs（@user_3c6cb52e/grill-with-docs）。它給 AI Agent 一套可複用的訪談紀律，並在會話過程中維護 CONTEXT.md 與 docs/adr/，還附帶若干僅依賴 Python 標準庫的校驗腳本，便於在追問前後做客觀檢查。

這是什麼¶

grill-with-docs 是社區來源（source: community）的 Agent Skill，分類爲 ai-agent，當前版本 1.0.0，發佈者爲 user_3c6cb52e。SkillHub 頁面標註 requires_api_key=false，安裝與使用不依賴額外 API Key。

Skill 包內的 SKILL.md 說明：核心規則衍生自 Matt Pocock 的 grill-with-docs（MIT）；本倉庫在保留訪談與文檔錨定規則的基礎上，增加了 3 個標準庫校驗腳本、3 份參考文檔，並在文檔中提及配套 agent/command（見後文注意項）。

官方入口：

• SkillHub 展示頁：https://www.skillhub.cn/skills/user_3c6cb52e/grill-with-docs
• 安裝座標：@user_3c6cb52e/grill-with-docs

核心功能¶

以下能力均來自已安裝的 Skill 包（SKILL.md 與同目錄文件），可按需裁剪使用。

訪談節奏與目標¶

Agent 被引導對當前計劃或設計做持續追問，沿設計樹逐枝深入，一次只問一個問題，並在每輪等待你的反饋後再繼續。若問題可通過讀代碼回答，應優先探索代碼庫而非空問。

會話目標包括：與用戶達成對方案的一致理解；在依賴關係上按決策逐項收斂。

與文檔結構的配合¶

Skill 假定倉庫中可能出現如下結構（單上下文或多上下文由是否存在 CONTEXT-MAP.md 區分）：

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

文件採用惰性創建：沒有 CONTEXT.md 時，在首個術語澄清後再建；沒有 docs/adr/ 時，在第一次需要 ADR 時再建。CONTEXT.md 僅作術語表與關係說明，不寫實現細節；格式見包內 CONTEXT-FORMAT.md。ADR 使用 docs/adr/NNNN-slug.md 編號，格式見 ADR-FORMAT.md。

會話中的四條紀律¶

1. 對照術語表：用戶用語與 CONTEXT.md 衝突時立即指出，並要求選定 canonical 含義。
2. 收緊模糊表述：對 overloaded 詞彙提議精確術語（例如區分 Customer 與 User）。
3. 用具體場景壓測：構造邊界場景，檢驗領域關係是否自洽。
4. 與代碼交叉驗證：陳述與實現不一致時，把矛盾點攤開讓用戶裁定。

術語一旦落定，應當場更新 CONTEXT.md，不要攢批。ADR 僅在同時滿足「難以逆轉」「缺上下文會顯得反常」「源於真實權衡」三項時才建議撰寫。

包裝層工具（stdlib）¶

Skill 提供三個 Python 腳本，用於訪談前後的確定性檢查：

推薦工作流（摘自 SKILL.md）：

1. 開場前：若已有 CONTEXT.md / docs/adr/，先跑 linter 與 scanner；對 src/ 跑 glossary 一致性，把告警當作首輪追問素材。
2. 進行中：維持「一輪一問」；改術語後必要時重跑 linter；新增 ADR 後重跑 adr_scanner.py。
3. 收尾：再跑一遍 glossary_code_consistency.py，彙總新增術語、ADR 與未決項。

示例命令（在倉庫根目錄，路徑按你的 Skill 安裝位置調整）：

python3 scripts/context_md_linter.py CONTEXT.md
python3 scripts/adr_scanner.py docs/adr/
python3 scripts/glossary_code_consistency.py --context CONTEXT.md --code src/

安裝與啓用¶

安裝 SkillHub CLI¶

若本機尚未安裝，可按 SkillHub 官方說明執行（完整安裝或僅 CLI）：

command -v skillhub && skillhub --version

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

文檔：https://skillhub.cn/install/skillhub.md

安裝 grill-with-docs¶

安裝時必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認落在 ./skills/ 可能不會被識別。

skillhub install grill-with-docs --namespace user_3c6cb52e --dir <你的 skills 目錄>

常見路徑（來自 SkillHub 安裝文檔）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或項目下的 .agents/skills/

SKILL.md frontmatter 中列出的框架還包括 Hermes Agent、OpenClaw、QClaw、WorkBuddy 等；各客戶端以「能加載該目錄下的 SKILL.md」爲準，具體菜單名稱因產品而異。

安裝完成後，在 Agent 中啓用或引用 @user_3c6cb52e/grill-with-docs，讓模型按 SKILL.md 中的 <what-to-do> 與 <supporting-info> 執行即可。

典型用法¶

用自然語言啓動一場「帶文檔的拷問」¶

把 Skill 加載到 Agent 後，可直接給出與上游一致的意圖（SKILL.md 原文要點）：

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. Ask the questions one at a time, waiting for feedback on each question before continuing. If a question can be answered by exploring the codebase, explore the codebase instead.

中文場景下可等價表述爲：請針對當前方案逐條追問，每輪一個問題並給出你的推薦答案；能查代碼就先查代碼；澄清的術語寫入 CONTEXT.md，滿足 ADR 三條件時再寫 docs/adr/。

在已有 CONTEXT 的倉庫裏續談¶

若根目錄已有 CONTEXT.md，先跑 linter，再開始訪談，可減少「術語表本身格式不對」帶來的噪音：

python3 path/to/grill-with-docs/scripts/context_md_linter.py CONTEXT.md

Agent 在會話中應持續對照 glossary，並在你確認後即時改文件，而不是會話結束再補文檔。

適用場景與注意¶

適合誰

• 需要在開工前把領域語言、邊界場景和關鍵取捨講清楚的技術負責人或結對小組。
• 希望 CONTEXT.md 與 ADR 與代碼同倉維護、可 diff 可評審的團隊。

限制與注意

• SkillHub 簡介僅一句泛化描述；實際行爲以包內 SKILL.md 爲準。安裝後建議通讀 CONTEXT-FORMAT.md、ADR-FORMAT.md 與 references/ 下的說明。
• SKILL.md 提到 companion：cs-grill-with-docs agent 與 /cs:grill-with-docs 命令，路徑指向包外的 ../../agents/、../../commands/。當前 SkillHub 下載包內主要爲 SKILL.md、格式說明、參考文檔與 scripts/；若你的環境沒有對應 command 定義，直接依賴 Skill 正文即可。
• 社區頁統計（以抓取資料爲準）：評分 100000，下載 10810，安裝計數 0；數據會隨平臺更新變化，引用時以 SkillHub 頁面爲準。
• 校驗腳本爲輔助手段，不能替代人對 trade-off 的判斷；訪談仍應「一輪一問」，避免模型一次性拋出過長問卷。

結尾¶

grill-with-docs 把「高強度方案訪談」和「術語表 + ADR」綁在同一套 Agent 紀律裏，並用標準庫腳本把文檔與代碼的一致性做成可重複檢查的步驟。若你正在用 Cursor、Claude Code 或 Codex 等支持 Skills 的客戶端，可通過 SkillHub 安裝 @user_3c6cb52e/grill-with-docs，在真實倉庫裏從一場單問單答的 grilling 開始，把共識寫進 CONTEXT.md 和 docs/adr/。

官方地址：https://www.skillhub.cn/skills/user_3c6cb52e/grill-with-docs