AI Skills
codebase-onboarding

codebase-onboarding

熱門

分析不熟悉的程式碼庫，產生結構化的入門指南，包含架構圖、關鍵進入點、慣例以及一份初始的 CLAUDE.md。適用於加入新專案或首次在儲存庫中設定 Claude Code 時使用。

23萬星標
3.5萬分支
更新於 2026/7/14
獲取技能源代碼

相關技能

debugging-and-error-recovery7.7萬hyperframes-media2.9萬n8n-workflow-patterns5785
SKILL.md
readonlyread-only
name
codebase-onboarding
description

Analyze an unfamiliar codebase and generate a structured onboarding guide with architecture map, key entry points, conventions, and a starter CLAUDE.md. Use when joining a new project or setting up Claude Code for the first time in a repo.

Codebase Onboarding

系統性地分析不熟悉的程式碼庫，並產出結構化的入門指南。專為首次加入新專案或首次在現有儲存庫中設定 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 平台

架構模式

  • 單體、單一儲存庫、微服務或無伺服器
  • 前後端分離或全端
  • API 風格：REST, GraphQL, gRPC, tRPC

關鍵目錄
將頂層目錄對應到其用途：

<!-- 以 React 專案為例 — 請替換為偵測到的目錄 -->

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 型別, 錯誤碼
  • 依賴注入或直接匯入
  • 狀態管理方式
  • 非同步模式：callbacks, promises, async/await, channels

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 已存在，請先讀取並增強它 — 保留現有的專案專屬指示，並清楚標註新增或變更的內容。

# 專案指示

## 技術棧
[偵測到的棧摘要]

## 程式碼風格
- [偵測到的命名慣例]
- [偵測到的應遵循模式]

## 測試
- 執行測試：`[detected test command]`
- 測試模式：[偵測到的測試檔案慣例]
- 涵蓋率：[若有設定，則為涵蓋率指令]

## 建置與執行
- 開發：`[detected dev command]`
- 建置：`[detected build command]`
- Lint：`[detected lint command]`

## 專案結構
[關鍵目錄 → 用途對應]

## 慣例
- [提交風格，若可偵測]
- [PR 工作流程，若可偵測]
- [錯誤處理模式]

最佳實務

  1. 不要讀取所有內容 — 偵查應使用 Glob 和 Grep，而非對每個檔案進行 Read。僅在訊號不明確時選擇性讀取。
  2. 驗證，不要猜測 — 如果從設定檔偵測到某個框架，但實際程式碼使用不同框架，請相信程式碼。
  3. 尊重現有的 CLAUDE.md — 如果已存在，請增強而非取代。標註哪些是新增的，哪些是原有的。
  4. 保持簡潔 — 入門指南應能在 2 分鐘內掃讀完畢。細節應留在程式碼中，而非指南中。
  5. 標註未知項目 — 如果無法自信地偵測某個慣例，請如實告知，而非猜測。「無法確定測試執行器」勝過錯誤答案。

應避免的反模式

  • 產生超過 100 行的 CLAUDE.md — 保持聚焦
  • 列出所有相依套件 — 僅凸顯那些影響你如何撰寫程式碼的套件
  • 描述顯而易見的目錄名稱 — src/ 不需要解釋
  • 複製 README — 入門指南應提供 README 所缺乏的結構性洞察

範例

範例 1：首次進入新儲存庫

使用者：「幫我入門這個程式碼庫」
動作：執行完整的 4 階段工作流程 → 產出入門指南 + 初始 CLAUDE.md
輸出：入門指南直接列印到對話中，並在專案根目錄寫入 CLAUDE.md

範例 2：為現有專案產生 CLAUDE.md

使用者：「為這個專案產生 CLAUDE.md」
動作：執行階段 1-3，跳過入門指南，僅產出 CLAUDE.md
輸出：專案專屬的 CLAUDE.md，包含偵測到的慣例

範例 3：增強現有的 CLAUDE.md

使用者：「用目前的專案慣例更新 CLAUDE.md」
動作：讀取現有的 CLAUDE.md，執行階段 1-3，合併新的發現
輸出：更新後的 CLAUDE.md，新增內容清楚標記