程式碼庫入門
系統性地分析一個陌生的程式碼庫，並產生結構化的入門指南。專為加入新專案的開發者，或首次在現有儲存庫中設定 Claude Code 的使用者而設計。
何時使用
- 首次使用 Claude Code 開啟專案
- 加入新的團隊或儲存庫
- 使用者詢問「幫我理解這個程式碼庫」
- 使用者要求為專案產生一份 CLAUDE.md
- 使用者說「引導我入門」或「帶我瀏覽這個儲存庫」
運作方式
第一階段：偵察
在不讀取每個檔案的情況下，收集關於專案的原始訊號。並行執行以下檢查：
1. 套件清單偵測
→ package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, build.gradle,
Gemfile, composer.json, mix.exs, pubspec.yaml
2. 框架指紋識別
→ next.config.*, nuxt.config.*, angular.json, vite.config.*,
django 設定, flask 應用工廠, fastapi 主程式, rails 設定
3. 入口點識別
→ main.*, index.*, app.*, server.*, cmd/, src/main/
4. 目錄結構快照
→ 目錄樹的前兩層，忽略 node_modules, vendor,
.git, dist, build, __pycache__, .next
5. 設定與工具偵測
→ .eslintrc*, .prettierrc*, tsconfig.json, Makefile, Dockerfile,
docker-compose*, .github/workflows/, .env.example, CI 設定檔
6. 測試結構偵測
→ tests/, test/, __tests__/, *_test.go, *.spec.ts, *.test.js,
pytest.ini, jest.config.*, vitest.config.*
第二階段：架構對應
從偵察資料中，識別：
技術棧
- 語言與版本限制
- 框架與主要函式庫
- 資料庫與 ORM
- 建置工具與打包工具
- CI/CD 平台
架構模式
- 單體、單體儲存庫、微服務或無伺服器
- 前端/後端分離或全端
- API 風格：REST、GraphQL、gRPC、tRPC
關鍵目錄 將頂層目錄對應到其用途：
src/components/ → React UI 元件
src/api/ → API 路由處理器
src/lib/ → 共用工具
src/db/ → 資料庫模型與遷移
tests/ → 測試套件
scripts/ → 建置與部署腳本
資料流 追蹤一個請求從入口到回應的路徑：
- 請求從哪裡進入？（路由器、處理器、控制器）
- 如何驗證？（中介軟體、結構描述、守衛）
- 業務邏輯在哪裡？（服務、模型、使用案例）
- 如何到達資料庫？（ORM、原始查詢、儲存庫）
第三階段：慣例偵測
識別程式碼庫已經遵循的模式：
命名慣例
- 檔案命名：kebab-case、camelCase、PascalCase、snake_case
- 元件/類別命名模式
- 測試檔案命名：
*.test.ts、*.spec.ts、*_test.go
程式碼模式
- 錯誤處理風格：try/catch、Result 型別、錯誤碼
- 依賴注入或直接匯入
- 狀態管理方法
- 非同步模式：回呼、Promise、async/await、通道
Git 慣例
- 近期分支的分支命名
- 近期提交的提交訊息風格
- PR 工作流程（壓縮合併、合併、變基）
- 如果儲存庫尚無提交或僅有淺層歷史（例如
git clone --depth 1），請跳過此部分並註明「Git 歷史不可用或過淺，無法偵測慣例」
第四階段：產生入門產出物
產出兩份結果：
產出物 1：入門指南
# 入門指南：[專案名稱]
## 概覽
[2-3 句話：此專案的用途與服務對象]
## 技術棧
<!-- 以 Next.js 專案為例 — 請根據偵測到的棧替換 -->
| 層級 | 技術 | 版本 |
|-------|-----------|---------|
| 語言 | TypeScript | 5.x |
| 框架 | Next.js | 14.x |
| 資料庫 | PostgreSQL | 16 |
| ORM | Prisma | 5.x |
| 測試 | Jest + Playwright | - |
## 架構
[描述元件如何連接的圖表或說明]
## 關鍵入口點
<!-- 以 Next.js 專案為例 — 請根據偵測到的路徑替換 -->
- **API 路由**：`src/app/api/` — Next.js 路由處理器
- **UI 頁面**：`src/app/(dashboard)/` — 已驗證頁面
- **資料庫**：`prisma/schema.prisma` — 資料模型的真相來源
- **設定**：`next.config.ts` — 建置與執行時設定
## 目錄對應
[頂層目錄 → 用途對應]
## 請求生命週期
[追蹤一個 API 請求從入口到回應的路徑]
## 慣例
- [檔案命名模式]
- [錯誤處理方法]
- [測試模式]
- [Git 工作流程]
## 常見任務
<!-- 以 Node.js 專案為例 — 請根據偵測到的指令替換 -->
- **執行開發伺服器**：`npm run dev`
- **執行測試**：`npm test`
- **執行 linter**：`npm run lint`
- **資料庫遷移**：`npx prisma migrate dev`
- **建置生產版本**：`npm run build`
## 相關位置
<!-- 以 Next.js 專案為例 — 請根據偵測到的路徑替換 -->
| 我想要... | 請查看... |
|--------------|-----------|
| 新增 API 端點 | `src/app/api/` |
| 新增 UI 頁面 | `src/app/(dashboard)/` |
| 新增資料庫表 | `prisma/schema.prisma` |
| 新增測試 | `tests/` 中的對應來源路徑 |
| 變更建置設定 | `next.config.ts` |
產出物 2：入門 CLAUDE.md
根據偵測到的慣例產生或更新一個專案專用的 CLAUDE.md。如果 CLAUDE.md 已存在，請先讀取並強化它 — 保留現有的專案專用說明，並清楚標示新增或修改的內容。
# 專案說明
## 技術棧
[偵測到的棧摘要]
## 程式碼風格
- [偵測到的命名慣例]
- [要遵循的偵測模式]
## 測試
- 執行測試：`[偵測到的測試指令]`
- 測試模式：[偵測到的測試檔案慣例]
- 涵蓋率：[如有設定，提供涵蓋率指令]
## 建置與執行
- 開發：`[偵測到的開發指令]`
- 建置：`[偵測到的建置指令]`
- Lint：`[偵測到的 lint 指令]`
## 專案結構
[關鍵目錄 → 用途對應]
## 慣例
- [提交風格（如可偵測）]
- [PR 工作流程（如可偵測）]
- [錯誤處理模式]
最佳實踐
- 不要讀取所有檔案 — 偵察應使用 Glob 和 Grep，而不是對每個檔案使用 Read。僅針對不明確的訊號有選擇性地讀取。
- 驗證，不要猜測 — 如果從設定中偵測到某個框架，但實際程式碼使用不同的框架，請相信程式碼。
- 尊重現有的 CLAUDE.md — 如果已存在，請強化它而不是取代它。明確標示新增與既有內容。
- 保持簡潔 — 入門指南應能在 2 分鐘內瀏覽完畢。細節應留在程式碼中，而非指南。
- 標示未知 — 如果無法自信地偵測到某個慣例，請直接說明，而不是猜測。「無法確定測試執行器」勝過一個錯誤的答案。
應避免的反模式
- 產生長度超過 100 行的 CLAUDE.md — 保持重點
- 列出每一個相依套件 — 僅強調那些會影響你如何撰寫程式碼的
- 描述顯而易見的目錄名稱 —
src/不需要解釋 - 複製 README — 入門指南提供了 README 所缺乏的結構性洞察
範例
範例 1：首次進入新儲存庫
使用者：「引導我進入這個程式碼庫」
動作：執行完整的 4 階段工作流程 → 產生入門指南 + 入門 CLAUDE.md
輸出：入門指南直接印在對話中，並將 CLAUDE.md 寫入專案根目錄
範例 2：為現有專案產生 CLAUDE.md
使用者：「為此專案產生 CLAUDE.md」
動作：執行第一至三階段，跳過入門指南，僅產生 CLAUDE.md
輸出：包含偵測到慣例的專案專用 CLAUDE.md
範例 3：強化現有 CLAUDE.md
使用者：「使用當前專案慣例更新 CLAUDE.md」
動作：讀取現有 CLAUDE.md，執行第一至三階段，合併新的發現
輸出：更新後的 CLAUDE.md，並清楚標示新增的內容