diegosouzapw 專案 Claude 配置初始化
為新專案建立標準化的 .claude 配置目錄，包含專案指引、gitignore 和目錄結構。
何時使用此 Skill
- 使用者說「初始化 Claude 配置」、「設定 Claude」
- 使用者說「為這個專案建立 .claude 目錄」
- 使用者說「幫我設定專案的 Claude Code」
- 開始新專案需要建立配置時
工作流程
步驟 1：確認專案資訊
先檢查當前目錄是否為專案根目錄，並收集專案資訊：
# 檢查是否在 git 倉庫中
git rev-parse --show-toplevel 2>/dev/null || pwd
# 檢查是否已有 .claude 目錄
[ -d ".claude" ] && echo "已存在" || echo "不存在"
如果不在專案根目錄，詢問使用者專案路徑。
使用 AskUserQuestion 收集資訊：
問題 1：專案名稱是什麼？
問題 2：主要技術棧？（選項：React/Vue/Node.js/Python/Java/Go/其他）
問題 3：是否需要建立 skills 目錄？（選項：是/否）
步驟 2：檢查現有配置（重要！）
必須先檢查是否已有配置，避免覆蓋使用者的設定。
# 檢查 .claude 目錄
ls -la .claude/ 2>/dev/null
# 檢查關鍵檔案
[ -f ".claude/CLAUDE.md" ] && echo "CLAUDE.md 已存在"
[ -f ".claude/settings.json" ] && echo "settings.json 已存在"
[ -f ".claude/.gitignore" ] && echo ".gitignore 已存在"
根據檢查結果採取不同策略：
情況 1：.claude 目錄不存在
- 直接建立完整配置
- 繼續步驟 3
情況 2：.claude 存在但 CLAUDE.md 不存在
- 保留現有檔案（settings.json, .gitignore 等）
- 只建立缺失的 CLAUDE.md
- 告知使用者：「發現現有配置，只建立缺失的檔案」
情況 3：CLAUDE.md 已存在但內容很少（< 10 行）
- 顯示現有內容
- 詢問使用者：
發現現有 CLAUDE.md（內容較少）： [顯示前 5 行] 選項： 1. 保留現有內容，不做修改 2. 備份現有檔案為 CLAUDE.md.backup，建立新檔案 3. 補充現有檔案（保留原有內容，添加缺失部分） 4. 取消操作
情況 4：CLAUDE.md 已存在且內容完整（> 10 行）
- 告知使用者：「CLAUDE.md 已存在且內容完整」
- 詢問是否要：
選項： 1. 保留現有配置，不做任何修改（推薦） 2. 檢視現有配置 3. 更新特定部分（技術棧、指令等） 4. 備份並重新建立
情況 5：有 settings.json 或其他配置
# 檢查是否有 settings.json
cat .claude/settings.json 2>/dev/null
- 絕對不要覆蓋 settings.json
- 如果存在，保留並跳過
- 告知使用者：「保留現有 settings.json」
情況 6：有自訂技能
# 檢查 skills 目錄
ls .claude/skills/ 2>/dev/null
- 保留所有現有技能
- 不要刪除或修改
- 告知使用者：「保留現有技能：[列出技能名稱]」
步驟 3：智慧掃描專案
根據專案檔案自動填充資訊：
Node.js 專案
# 讀取 package.json
cat package.json 2>/dev/null
從 package.json 提取：
- 專案名稱 (
name) - 描述 (
description) - 依賴套件（識別 React、Vue、Express、Next.js 等）
- scripts（dev、test、build）
Python 專案
# 讀取 pyproject.toml 或 requirements.txt
cat pyproject.toml 2>/dev/null || cat requirements.txt 2>/dev/null
識別：FastAPI、Django、Flask 等框架
其他專案
- Go: 讀取
go.mod - Rust: 讀取
Cargo.toml - Java: 讀取
pom.xml或build.gradle
掃描目錄結構
# 列出主要目錄
find . -maxdepth 2 -type d ! -path '*/\.*' ! -path './node_modules/*' | sort
步驟 4：建立目錄結構
mkdir -p .claude/skills
mkdir -p .claude/plans
步驟 5：建立 .gitignore
使用 Write 工具建立 .claude/.gitignore：
# ===== Claude Code 運行時資料 =====
# 除錯與快取
debug/
cache/
stats-cache.json
statsig/
telemetry/
file-history/
# 會話相關
session-env/
shell-snapshots/
todos/
ide/
# 歷史記錄
history.jsonl
# 專案快取
projects/
# ===== 敏感資料 =====
settings.local.json
.credentials.json
*.key
*.pem
*.env.local
# ===== 臨時檔案 =====
*.tmp
*.log
步驟 6：建立 CLAUDE.md
根據掃描結果建立 .claude/CLAUDE.md，使用以下模板並自動填充：
# [專案名稱]
## 專案簡介
[從 package.json 或使用者輸入填寫]
## 技術棧
[根據掃描結果自動列出]
- 前端：[自動偵測]
- 後端：[自動偵測]
- 測試：[自動偵測]
## 專案結構
[自動生成目錄樹]
## 開發規範
### 程式碼風格
[根據技術棧提供建議]
### 測試要求
[根據技術棧提供建議]
### Git 規範
- Commit message 遵循 Conventional Commits
- 分支命名：feature/*, fix/*, chore/*
## 常用指令
```bash
[從 package.json scripts 自動提取]
特殊注意事項
[預留給使用者填寫]
### 步驟 7：技術棧特定建議
根據識別的技術棧，提供相應的規範建議：
#### React/TypeScript 專案
```markdown
## 開發規範
### 程式碼風格
- 使用 TypeScript strict mode
- 元件使用函式式寫法 + hooks
- 元件命名使用 PascalCase
- 檔案命名使用 kebab-case
### 測試要求
- 元件測試覆蓋率 > 80%
- 使用 React Testing Library
- E2E 測試使用 Playwright
### 專案結構
- 元件放在 `src/components/`
- Hooks 放在 `src/hooks/`
- Utils 放在 `src/utils/`
Python/FastAPI 專案
## 開發規範
### 程式碼風格
- 遵循 PEP 8
- 使用 Black 格式化
- 使用 type hints
### 測試要求
- 使用 pytest
- 測試覆蓋率 > 85%
- 包含整合測試
### 專案結構
- API routes 放在 `app/routes/`
- Models 放在 `app/models/`
- Services 放在 `app/services/`
步驟 8：生成目錄樹
使用適當的方式生成目錄結構：
# Linux/Mac
tree -L 2 -d --gitignore -I 'node_modules|.git' || find . -maxdepth 2 -type d ! -path '*/\.*' ! -path './node_modules/*'
# 或手動整理
ls -la | grep ^d
步驟 9：確認並完成
- 顯示將要建立的檔案清單
- 展示 CLAUDE.md 預覽
- 詢問使用者是否確認
- 建立所有檔案
- 提示後續步驟
步驟 10：提交到版控
提示使用者將配置加入 git：
git add .claude/
git commit -m "docs: 初始化 Claude Code 專案配置"
輸出範例
成功訊息
✓ 已建立 .claude 目錄結構
✓ 已建立 .claude/.gitignore
✓ 已建立 .claude/CLAUDE.md
✓ 已建立 .claude/skills/（空目錄）
✓ 已建立 .claude/plans/（空目錄）
專案配置已完成！
下一步：
1. 檢視 .claude/CLAUDE.md 並根據需要調整
2. 提交到版控：git add .claude/ && git commit -m "docs: 初始化 Claude Code 配置"
3. 開始使用：claude（Claude Code 會自動讀取配置）
團隊共享：
- 團隊成員 clone 專案後會自動獲得此配置
- 個人設定可放在 .claude/settings.local.json（已在 gitignore 中）
智慧功能
自動技術棧偵測
根據檔案特徵自動識別：
| 檔案/內容 | 識別為 |
|---|---|
| package.json + "react" | React |
| package.json + "next" | Next.js |
| package.json + "vue" | Vue.js |
| package.json + "express" | Express |
| requirements.txt + "fastapi" | FastAPI |
| requirements.txt + "django" | Django |
| go.mod | Go |
| Cargo.toml | Rust |
| pom.xml | Java/Maven |
自動指令提取
從配置檔案提取常用指令：
package.json:
{
"scripts": {
"dev": "vite",
"build": "tsc && vite build",
"test": "vitest"
}
}
自動生成：
## 常用指令
```bash
# 開發
npm run dev
# 建置
npm run build
# 測試
npm test
### 目錄結構智慧識別
識別常見結構並生成說明：
src/ ├── components/ # React 元件 ├── pages/ # 頁面元件 ├── hooks/ # 自訂 hooks ├── utils/ # 工具函式 └── types/ # TypeScript 類型定義
## 團隊共享說明
初始化完成後，告知使用者如何與團隊共享：
```markdown
## 團隊使用此配置
### 方式 1：專案配置（推薦）
此配置已加入專案 git，團隊成員 clone 後自動獲得。
### 方式 2：全局配置
如果團隊想共享通用技能：
1. 建立團隊配置倉庫
2. 成員 clone 到 ~/.claude
3. 全局 + 專案配置會自動合併
### 個人設定
如需個人覆蓋（API key 等）：
- 建立 .claude/settings.local.json
- 已在 gitignore 中，不會提交
特殊情況處理
情況 1：已有 .claude 目錄但無 CLAUDE.md
策略：安全增量
# 檢查現有檔案
ls -la .claude/
處理方式：
- ✅ 保留所有現有檔案（settings.json, skills/, plans/ 等）
- ✅ 只建立缺失的 CLAUDE.md
- ✅ 如果沒有 .gitignore，建立標準 .gitignore
- ✅ 告知使用者保留了哪些現有檔案
範例輸出：
✓ 發現現有配置
✓ 保留 settings.json
✓ 保留 skills/ 目錄（3 個技能）
✓ 建立 CLAUDE.md
✓ 建立 .gitignore
情況 2：已有完整配置（CLAUDE.md 存在）
策略：保守，詢問使用者
# 讀取現有 CLAUDE.md
wc -l .claude/CLAUDE.md # 計算行數
head -10 .claude/CLAUDE.md # 預覽前 10 行
根據內容長度：
如果 > 50 行（內容豐富）：
⚠️ 發現現有 CLAUDE.md（內容完整，82 行）
[顯示前 10 行預覽]
建議保留現有配置。選項：
1. 保留，不做任何修改（推薦）✅
2. 檢視完整內容
3. 僅更新技術棧部分
4. 備份後重新建立
如果 10-50 行（基礎內容）：
發現現有 CLAUDE.md（基礎配置，23 行）
選項：
1. 保留現有內容 ✅
2. 補充缺失部分（技術棧、指令等）
3. 備份後重新建立
4. 取消操作
如果 < 10 行（佔位內容）：
發現簡易 CLAUDE.md（5 行）：
---
[顯示內容]
---
建議重新建立完整配置。選項：
1. 備份後重新建立 ✅
2. 保留現有
3. 補充現有內容
情況 3：有 settings.json（使用者自訂設定）
策略：絕對保護
cat .claude/settings.json
處理方式：
- 🔒 絕對不覆蓋
- 🔒 絕對不修改
- ✅ 顯示內容給使用者
- ✅ 告知：「保留您的自訂設定」
範例輸出：
🔒 發現現有設定檔（settings.json）
包含自訂配置：
- model: "opus"
- maxTokens: 150000
✓ 保留所有自訂設定，不做任何修改
情況 4：有自訂技能（使用者創作）
策略：完全保護
ls .claude/skills/
處理方式：
- 🔒 不刪除任何技能
- 🔒 不修改任何技能
- ✅ 列出現有技能
- ✅ 告知：「保留所有自訂技能」
範例輸出：
✓ 發現現有技能：
- my-custom-skill
- team-coding-style
- project-specific-debug
✓ 保留所有技能，不做任何修改
情況 5：不在 git 倉庫中
策略：仍然建立，但提醒
git rev-parse --is-inside-work-tree 2>/dev/null || echo "不是 git 倉庫"
處理方式：
- ✅ 仍然建立配置（功能不受影響）
- ℹ️ 提醒：「此專案不在 git 版控中」
- 💡 建議：「考慮初始化 git（可選）」
範例輸出：
ℹ️ 注意：此專案不在 git 版控中
✓ Claude Code 配置已建立（不受影響）
💡 建議（可選）：
如果要版控此專案：
git init
git add .
git commit -m "Initial commit"
情況 6：找不到專案資訊
策略：使用通用模板 + 詢問
處理方式：
- ❓ 詢問基本資訊（專案名稱、技術棧）
- ✅ 使用通用模板
- ✅ 標記需要使用者補充的部分
範例輸出：
ℹ️ 無法自動偵測專案資訊
已建立基礎配置，請手動補充：
- [專案簡介] ← 請填寫
- [技術棧] ← 請填寫
- [常用指令] ← 請填寫
位置：.claude/CLAUDE.md
情況 7：團隊專案（有多人協作痕跡）
策略：特別謹慎
偵測條件：
# 檢查 git 作者數量
git log --format='%an' | sort -u | wc -l
# > 3 人 → 團隊專案
處理方式：
- ⚠️ 額外警告：「這是團隊專案」
- 💡 建議：「修改前先與團隊討論」
- ✅ 提供「唯讀檢視」選項
範例輸出：
⚠️ 偵測到團隊專案（5 位貢獻者）
建議：
1. 檢視現有配置（不做修改）✅
2. 與團隊討論後再修改
3. 只建立個人本地設定（settings.local.json）
是否繼續？
檢查清單
完成後確認：
-
.claude/.gitignore已建立 -
.claude/CLAUDE.md已建立且內容完整 - 專案名稱正確
- 技術棧資訊準確（如果能偵測到）
- 目錄結構已記錄
- 常用指令已填寫（如果能提取到）
- 使用者知道如何提交到 git
- 使用者知道如何與團隊共享
安全原則（🔒 絕對遵守）
絕對不可做的事
🔒 絕對不覆蓋 settings.json
- 如果存在 → 保留並跳過 → 告知使用者
🔒 絕對不刪除或修改現有技能
- skills/ 中的任何檔案 → 只列出，不修改
🔒 絕對不在未詢問下覆蓋 CLAUDE.md
- 如果 > 10 行 → 必須詢問 → 預設「保留現有」
🔒 絕對不刪除使用者資料
- plans/, conversation-archives/, 任何自訂檔案 → 保留
🔒 絕對不修改有自訂內容的 .gitignore
- 檢查是否有自訂規則 → 詢問是否補充（非替換）
安全操作流程
檢查 → 詢問 → 備份（如需） → 執行 → 確認
每一步必須：
- ✅ 明確告知使用者
- ✅ 顯示將要修改的內容
- ✅ 提供取消選項
- ✅ 操作後確認結果
注意事項
- 保守策略：有疑問時，選擇保留現有內容
- 透明操作：每個動作都告知使用者
- 可逆性：提供備份和還原選項
- 保持簡潔：CLAUDE.md 應該簡短實用，不要放太多細節
- 聚焦關鍵資訊：技術棧、規範、特殊注意事項
- 可擴展：為使用者留下自訂空間
- 團隊友善：在團隊專案中特別謹慎
進階選項（可選）
選項 1：建立專案特定技能模板
如果使用者選擇建立 skills 目錄，可提供建立第一個技能的指引。
選項 2：整合 CI/CD 配置
如果偵測到 GitHub/GitLab，提供 CI/CD 整合建議。
選項 3：建立開發文件結構
建議建立 docs/ 目錄並提供模板。