程式碼庫入門引導 是做什麼的？
系統化分析陌生的程式碼庫，產出結構化的入門引導指南。專為初次加入新專案或首次在現有儲存庫中設定 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 settings, flask app factory, fastapi main, rails config
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 configs
6. 測試結構偵測
→ tests/, test/, __tests__/, *_test.go, *.spec.ts, *.test.js,
pytest.ini, jest.config.*, vitest.config.*
第二階段：架構映射
從偵察資料中識別：
技術棧
- 語言與版本限制
- 框架與主要函式庫
- 資料庫與 ORM
- 建置工具與打包工具
- CI/CD 平台
架構模式
- 單體、Monorepo、微服務或無伺服器
- 前後端分離或全端
- API 風格：REST、GraphQL、gRPC、tRPC
關鍵目錄 將頂層目錄對應到其用途：
src/components/ → React UI 元件
src/api/ → API 路由處理程式
src/lib/ → 共用工具
src/db/ → 資料庫模型與遷移
src/ → 目前無特定說明
tests/ → 測試套件
scripts/ → 建置與部署腳本
資料流程 追蹤一個請求從進入到回應的路徑：
- 請求從哪裡進入？（路由器、處理程式、控制器）
- 如何驗證？（中介軟體、Schema、防護）
- 商業邏輯在哪裡？（服務、模型、Use Case）
- 如何到達資料庫？（ORM、原始查詢、Repository）
第三階段：慣例偵測
識別程式碼庫已遵循的模式：
命名慣例
- 檔案命名：kebab-case、camelCase、PascalCase、snake_case
- 元件/類別命名模式
- 測試檔案命名：
*.test.ts、*.spec.ts、*_test.go
程式碼模式
- 錯誤處理風格：try/catch、Result 類型、錯誤碼
- 依賴注入或直接匯入
- 狀態管理方式
- 非同步模式：回呼、Promise、async/await、Channel
Git 慣例
- 從近期分支識別分支命名
- 從近期提交識別提交訊息風格
- PR 工作流程（Squash、Merge、Rebase）
- 如果儲存庫尚無提交或只有淺層歷史（例如
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`
- **執行 lint**：`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，並清楚標示新增內容