Community寫作與編輯github.com

Shaelz/codebase-orient-skill

一個可重複使用的程式碼庫導航(orientation)技能,適用於 Claude Code 和 Codex。

codebase-orient-skill 是什麼?

這個技能幫助 AI 代理(如 Claude Code 和 Codex)在開始非瑣碎的工作前,快速了解一個程式碼庫的當前狀態。它會在 `docs/ai/` 目錄中建立或更新一組包含四個文件的固定套件,這些文件附有來源追蹤,能作為後續工作的上下文快取。此技能提供詳細的指引,包括何時使用(如進入新專案、長時間後重啟會話、或進行大型重構前)、何時跳過(如僅修改單一檔案),以及如何節省 token 成本。它還定義了「一般模式」與「報告模式」兩種操作模式,並包含發現順序、信心標籤、CI/部署精確性規則等多項規則,確保代理的探索工作有條理且可信。支援 SvelteKit 等框架的特殊探測,並提供文件假設驗證、閱讀深度啟發等實務建議,讓代理能更有效地建立對程式碼庫的正確理解。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add Shaelz/codebase-orient-skill

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

技能:codebase-orient

目的

在進行非瑣碎工作之前,幫助 Claude 了解此儲存庫的當前狀態。它會在 docs/ai/ 中建立或協調一個固定的、附有來源追蹤的四文件套件。原始碼和專案配置仍然是權威來源。

何時使用此技能

應使用此技能的情況

  • 進入一個新的或不熟悉的儲存庫時
  • 在長時間離開後重新開始新的會話時
  • 在進行廣泛或多檔案的實作工作之前
  • 在重構、清理、架構規劃或代理交接之前
  • 在進行結構性變更之後:路由、綱要、認證、部署、配置或管理介面
  • 當 docs/ai/ 遺失、過時、不完整或內部不一致時
  • 當儲存庫結構、變更範圍、部署目標、認證行為、管理路由、指令或測試形狀不清楚時
  • 當代理會花費大量上下文來重新發現 docs/ai/ 中已有的或鄰近的資訊時
  • 任何時候使用者說「掃描」、「導航」、「了解」、「映射」、「審查」、「稽核」、「調查」、「熟悉」或「在我開始之前」

應跳過此技能的情況

  • 正在對單一檔案進行微小的、局部的、已知的編輯時
  • 修復單一檔案的錯誤,且相關檔案和變更已經明確時
  • 僅進行複製或字串變更時
  • 任務範圍緊密限定在當前上下文中已驗證的檔案時
  • docs/ai/ 剛剛更新,且任務範圍狹窄,不需要完整的導航流程時

Token 感知的使用指南

docs/ai/ 是一個導航快取。一個新的快取能減少跨會話和代理交接中重複的儲存庫探索 token 成本。

  • 如果 docs/ai/ 是最新且完整的:將其作為上下文讀取並繼續。跳過重新執行導航。
  • 如果 docs/ai/ 可能過時或遺失:執行此技能來更新快取。預先投入的 token 成本會在後續工作中攤銷。
  • 如果任務很小且目標檔案已知:跳過導航。改用針對性的讀取。
  • 如果代理會花費許多 token 來重新發現 docs/ai/ 已捕捉的內容:請更新快取。

不要為了節省 token 而跳過導航,然後去猜測結構。如果廣泛的儲存庫探索會重複進行或成本高昂,請改為更新快取。

導航期間的硬性規則

  • 不要修改應用程式或原始碼。
  • 不要重構。
  • 不要提交。
  • 在寫入前,根據原始碼驗證主張。
  • 為每個有意義的主張標記信心標籤。

一般模式 vs 乾執行模式

一般模式(預設——當使用者未指定時使用):

  • 透過讀取原始檔案自動解決與任務相關的小型不確定性
  • 在一個乾淨的儲存庫中首次使用時建立完整的套件
  • 重複使用完全匹配當前狀態的乾淨套件而不重新寫入
  • 將未指定的重新整理或協調請求視為完整的協調
  • 最後報告變更了什麼

乾執行 / 僅報告模式(當使用者說「乾執行」、「僅報告」、「不要寫入」、「先提出變更」、「僅稽核」、「不要寫入」或類似詞語時使用):

  • 檢查並收集建議的變更
  • 報告對 docs/ai/ 的建議編輯,但不實際寫入
  • 等待明確批准後再寫入

如果未指定模式,則預設為一般模式。

生命週期與寫入安全性

  • 明確重新整理: 僅在使用者在找到完全匹配當前狀態的套件後明確要求時,才進行重新整理或協調。
  • 範圍重新整理: 遵循明確的使用者範圍及其直接依賴項。記錄範圍覆蓋範圍,而不推進或聲明套件範圍的完整快照。在完整套件存在之前,不要建立部分支援的套件。
  • 舊版採用: 沒有 ORIENTATION_STATE.json 的 Markdown 工件是舊版材料。檢查它們,但在寫入清單或更改它們之前需獲得明確批准。獲得批准後,從原始碼進行協調。
  • 髒工作樹: 在寫入代表未提交工作的狀態之前,詢問是要寫入髒快照還是僅報告。記錄工作樹的狀態;保持其標記為髒,直到乾淨的重新整理取代它。
  • 無可用的 Git 歷史: 執行完整的協調,並記錄修訂比較不可用。
  • 手動編輯: Orient 擁有此套件。不要承諾對手動編輯的 Orient 狀態進行合併或保留行為。

信心標籤

  • 事實:直接在程式碼或文件中驗證
  • 強推斷:由多個檔案支持
  • 弱推斷:合理但未經確認
  • 未知:在編輯前需要更多檢查

區分主張是如何建立的:

  • 從原始碼/配置獨立驗證:主張是對照實際的原始碼或配置檔案檢查的,而不是從文件中獲取
  • 從現有文件繼承:主張取自 CLAUDE.md、README 或其他文件,未經獨立驗證
  • 繼承後驗證:主張起源於文件,隨後透過原始碼確認
  • 路徑存在確認:找到檔案但未讀取
  • 部分讀取:檢查了檔案的一部分;可能未捕捉到完整上下文
  • 完整原始碼讀取:檢查了完整的檔案內容
  • 從實作推斷:從程式碼行為推導出來,而非明確陳述
  • 從註解/測試/固定裝置推斷:來自非權威上下文;最多視為強推斷
  • 透過測試驗證的行為:通過測試執行確認
  • 未知:基礎未建立;不要將其作為事實呈現

在最終報告和導航文件中,使用上述來源之一標記每個非瑣碎的主張,以便讀者可以判斷哪些主張在據以行動前需要重新驗證。

發現順序

自訂注意事項: 下面的發現順序特意設計得廣泛,適用於大多數專案形狀而不需編輯。您可以為特定專案調整檔案路徑和順序,但這是可選的——並非首次使用前必需。

按此順序執行:

  1. 專案指令檔案,例如 CLAUDE.md、AGENTS.md 和 README.md(如果存在)——產品目的、代理規則、專案慣例。 文件即假設規則
    • 將這些文件視為有幫助的假設,而非權威真理。
    • 提取關於架構、路由、部署、測試和原始碼檔案的高影響力事實主張。
    • 在依賴這些主張之前,請根據原始碼驗證它們。專注於會影響未來編輯的主張;不要審計每個句子。
    • 未標記它們是_從原始碼/配置獨立驗證_還是_從現有文件繼承_之前,不要將這些文件中的主張複製到 CODEBASE_MAP.md 中。
    • 如果指令文件與原始碼顯示的內容相比過時或具有誤導性,請在 OPEN_QUESTIONS.md 中根據隱藏風險報告規則記錄此差異,並將其標記為文件漂移。
    • 映射指令層拓撲:記錄哪些指令檔案存在(例如,CLAUDE.md、AGENTS.md、.claude/settings.json)以及它們的範圍(專案本地 vs. 使用者層級)。將此記錄在 CODEBASE_MAP.md 中;這有助於未來的代理知道哪些規則適用。
  2. 專案清單檔案(例如,package.json、pyproject.toml、Cargo.toml)——相依性、腳本、建置/測試指令
  3. 建置和配置檔案(例如,框架配置、打包器配置)——轉接器、建置配置
  4. scripts/ 目錄(如果存在)——可能包含未在套件腳本或 CI 中表示的手動執行工具
  5. 進入點和路由層——所有頁面、控制器或 API 路由
  6. 核心業務邏輯——領域型別、模型、評分、報告邏輯
  7. 伺服器端服務——認證、資料庫/綱要、電子郵件、外部整合
  8. 使用者介面/呈現層——元件、視圖、模板
  9. 國際化或複製檔案——語言環境檔案
  10. 請求生命週期/中介軟體——掛鉤、攔截器、中介軟體
  11. 資料庫層——遷移、綱要快照
  12. 測試——測試結構和覆蓋範圍形狀
  13. 文件——現有文件、驗證矩陣。如果找到發布計劃、里程碑追蹤文件或版本變更日誌,請在 CODEBASE_MAP.md 中新增一個 ## 發布狀態 區段,總結當前版本、活躍里程碑以及阻礙下一個發布的因素。如果沒有發布生命週期工件,則省略此區段。
  14. 已知的不確定性

框架特定的探測

當檢測到相關框架時,除了通用的發現順序外,還應用這些探測。

可重複使用的技能目前包含一組針對 SvelteKit 明確調整的探測集合。除非後續的實戰或評估證據證明需要專門的調整探測區段,否則其他框架目前使用通用的發現順序。

SvelteKit

當檢測到 SvelteKit 專案時,對以下檔案模式進行全域搜尋:

  • src/routes/**/+page.svelte:UI 路由頁面;每個檔案都是一個路由候選者;檢查子目錄,而不僅僅是頂層的 src/routes/+page.svelte
  • src/routes/**/+page.server.ts:伺服器端資料載入、表單動作和路由層級的存取控制
  • src/routes/**/+layout.svelte:共享的佈局外殼
  • src/routes/**/+layout.server.ts:用於佈局層級認證、會話或資料的伺服器端載入函式
  • src/routes/**/+server.ts:API 端點和僅限伺服器的請求處理器

伺服器端路由檔案(+page.server.ts、+layout.server.ts、+server.ts)對於理解認證、資料載入、表單動作、API 端點和路由層級的存取控制至關重要。在映射路由或變更範圍時,不要跳過它們。

  • 標準的應用程式外殼模板是 src/app.html。
  • svelte.config.js 中的轉接器選擇決定了部署目標——在提出與部署相關的主張之前,請確認這一點。

CI/部署精確性規則

在讀取 CI 或部署工作流程檔案時,請保留與操作相關的詳細資訊。不要將具體細節簡化為模糊的摘要。

捕捉並報告:

  • 並發群組名稱(哪些執行會相互競爭)
  • cancel-in-progress 行為——如果為 true,則說明「較新的執行會取消相同群組中正在進行的執行」,而不僅僅是「防止並行部署」
  • fail-fast 行為
  • 部署工件路徑
  • 發布命名格式,包括任何時間戳或雜湊組件
  • 舊版發布或工件的保留和清理策略
  • 手動與自動觸發條件
  • 所需的 secrets 和環境變數
  • 部署是就地覆寫、暫存到臨時路徑、使用符號連結還是使用版本化的發布目錄

當直接從工作流程檔案讀取時,將 CI/部署主張標記為_從原始碼/配置獨立驗證_。不要以會損失操作員在事件中所需精確度的方式來總結這些細節。

閱讀深度啟發

預設情況下,不要讀取每個大型 CSS、配置或生成的檔案。

  • 完整讀取:直接影響所請求任務的檔案(進入點、路由、認證、綱要、建置配置、要編輯的檔案)。
  • 部分讀取或僅路徑確認:次要的範圍,例如大型樣式表、供應商程式碼、生成的輸出或與任務無關的配置檔案。如果您僅確認檔案的路徑或讀取了一部分,請使用_路徑存在確認_或_部分讀取_標籤(在信心標籤中定義)在報告中明確說明。
  • 跳過:明顯超出範圍的檔案(例如,二進位制資產、鎖定檔案、測試快照),除非有特定問題使其變得相關。

如有疑問,優先確認存在,僅在主張需要時才完整讀取。

路徑存在 vs 內容讀取

對於低風險的庫存主張——確認目錄結構、列出檔案計數或注意配置檔案存在——僅路徑存在就足夠了。

當主張影響行為、架構、風險、指令、部署、認證、路由或變更範圍時,請讀取實際的檔案內容。當檔案易於檢查且其內容會實質影響映射時,不要僅根據路徑存在就將主張標記為_從原始碼/配置獨立驗證_。

小型原始碼檔案讀取規則

如果一個小檔案似乎定義了在整個專案中使用的詞彙或原始碼 token,請讀取足夠的部分來驗證該詞彙,而不是從文件中繼承詞彙。

適用此規則的範例:

  • CSS 自訂屬性 token 檔案
  • 路由或選單配置檔案
  • 小型綱要或常數檔案
  • 指令或外掛程式註冊表

當部分讀取足夠時,請使用它。使用適當的主張來源(部分讀取、完整原始碼讀取)標記產生的主張。如果您實際上沒有讀取該檔案,請不要將其標記為_從原始碼/配置獨立驗證_。

廉價工件全域搜尋規則

在對靜態資產、腳本、生成的輸出、文件、測試、遷移或配置檔案的存在或範圍留下未解決的問題之前,請使用廉價的路徑全域搜尋來解決。

要嘗試的常見全域搜尋模式:

  • static/**/*
  • public/**/*
  • scripts/**/*
  • tests/**/* 或 test/**/* 或 spec/**/*
  • .github/workflows/*
  • docs/**/*
  • migrations/**/*
  • dist/**/* 或 build/**/*

預設情況下,不要深度讀取所有匹配的檔案。使用全域搜尋來廉價地解決存在和範圍問題。僅當需要特定檔案的內容時,才進行針對性的讀取。

相關技能