技能: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 或其他文件,未經獨立驗證
- 繼承後驗證:主張起源於文件,隨後透過原始碼確認
- 路徑存在確認:找到檔案但未讀取
- 部分讀取:檢查了檔案的一部分;可能未捕捉到完整上下文
- 完整原始碼讀取:檢查了完整的檔案內容
- 從實作推斷:從程式碼行為推導出來,而非明確陳述
- 從註解/測試/固定裝置推斷:來自非權威上下文;最多視為強推斷
- 透過測試驗證的行為:通過測試執行確認
- 未知:基礎未建立;不要將其作為事實呈現
在最終報告和導航文件中,使用上述來源之一標記每個非瑣碎的主張,以便讀者可以判斷哪些主張在據以行動前需要重新驗證。
發現順序
自訂注意事項: 下面的發現順序特意設計得廣泛,適用於大多數專案形狀而不需編輯。您可以為特定專案調整檔案路徑和順序,但這是可選的——並非首次使用前必需。
按此順序執行:
- 專案指令檔案,例如
CLAUDE.md、AGENTS.md和README.md(如果存在)——產品目的、代理規則、專案慣例。 文件即假設規則- 將這些文件視為有幫助的假設,而非權威真理。
- 提取關於架構、路由、部署、測試和原始碼檔案的高影響力事實主張。
- 在依賴這些主張之前,請根據原始碼驗證它們。專注於會影響未來編輯的主張;不要審計每個句子。
- 未標記它們是_從原始碼/配置獨立驗證_還是_從現有文件繼承_之前,不要將這些文件中的主張複製到
CODEBASE_MAP.md中。 - 如果指令文件與原始碼顯示的內容相比過時或具有誤導性,請在
OPEN_QUESTIONS.md中根據隱藏風險報告規則記錄此差異,並將其標記為文件漂移。 - 映射指令層拓撲:記錄哪些指令檔案存在(例如,
CLAUDE.md、AGENTS.md、.claude/settings.json)以及它們的範圍(專案本地 vs. 使用者層級)。將此記錄在CODEBASE_MAP.md中;這有助於未來的代理知道哪些規則適用。
- 專案清單檔案(例如,
package.json、pyproject.toml、Cargo.toml)——相依性、腳本、建置/測試指令 - 建置和配置檔案(例如,框架配置、打包器配置)——轉接器、建置配置
scripts/目錄(如果存在)——可能包含未在套件腳本或 CI 中表示的手動執行工具- 進入點和路由層——所有頁面、控制器或 API 路由
- 核心業務邏輯——領域型別、模型、評分、報告邏輯
- 伺服器端服務——認證、資料庫/綱要、電子郵件、外部整合
- 使用者介面/呈現層——元件、視圖、模板
- 國際化或複製檔案——語言環境檔案
- 請求生命週期/中介軟體——掛鉤、攔截器、中介軟體
- 資料庫層——遷移、綱要快照
- 測試——測試結構和覆蓋範圍形狀
- 文件——現有文件、驗證矩陣。如果找到發布計劃、里程碑追蹤文件或版本變更日誌,請在
CODEBASE_MAP.md中新增一個## 發布狀態區段,總結當前版本、活躍里程碑以及阻礙下一個發布的因素。如果沒有發布生命週期工件,則省略此區段。 - 已知的不確定性
框架特定的探測
當檢測到相關框架時,除了通用的發現順序外,還應用這些探測。
可重複使用的技能目前包含一組針對 SvelteKit 明確調整的探測集合。除非後續的實戰或評估證據證明需要專門的調整探測區段,否則其他框架目前使用通用的發現順序。
SvelteKit
當檢測到 SvelteKit 專案時,對以下檔案模式進行全域搜尋:
src/routes/**/+page.svelte:UI 路由頁面;每個檔案都是一個路由候選者;檢查子目錄,而不僅僅是頂層的src/routes/+page.sveltesrc/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/**/*
預設情況下,不要深度讀取所有匹配的檔案。使用全域搜尋來廉價地解決存在和範圍問題。僅當需要特定檔案的內容時,才進行針對性的讀取。