# ty-ai-standards 新專案接入指令書 > Legacy notice: 本文件屬於 Claude 時代的 onboarding 指南，保留供歷史查閱，不再是本專案正式規範。 > 目前請以根目錄 `AGENTS.md`、`CONSTITUTION.md`、`docs/adr/README.md`、`docs/memory/README.md` 為準。 > 本文件由統帥產生，可直接轉發給負責新專案的 Claude Code session。 > 執行前無需額外背景知識，照順序執行即可。 --- ## 一、你的任務 將本機已建立的「ty-ai-standards 全域架構」套用到 **這個專案**。 全域架構已就緒於 `~/.claude/`，你的工作是為本專案建立 **Local 層**。 --- ## 二、全域架構現況（已完成，勿修改） `~/.claude/` 已包含： | 路徑 | 內容 | |------|------| | `~/.claude/CLAUDE.md` | 全域憲法：P7/P9/P10、三紅線、12-agent 委派表 | | `~/.claude/settings.json` | 全域設定：claude-sonnet-4-6 + 10 個 hooks | | `~/.claude/hooks/` | 10 個 hook：branch-protection / commit-quality / python-quality / yaml-validator / large-file-warner / mcp-health / audit-log / suggest-compact / cost-tracker / session-summary | | `~/.claude/agents/` | 10 個 agent：critic / debugger / planner / fullstack-engineer / refactor-specialist / migration-engineer / onboarder / tool-expert / vuln-verifier / web-researcher | **全域 hooks 在本 session 已自動生效，無需重複安裝。** --- ## 三、hooks 合併規則（必讀） Claude Code 的 hooks 採 **全域 + 專案 同時執行**（不覆蓋，疊加）。 因此： - 全域 `commit-quality.js` 已掃描通用 secret（OpenAI / GitHub / AWS / Anthropic） + 讀取本專案的 `.claude/hooks/secrets.local.json` 補充專案專屬 pattern - **本專案 settings.json 不需要再呼叫 commit-quality.js**（避免重複執行） --- ## 四、P7 執行計畫（六步，逐步完成） ### Step 1 — 讀取現況（禁止跳過） 執行以下指令，**全部讀完再開始動手**： ```bash # 1a. 確認全域架構 ls ~/.claude/hooks/ ls ~/.claude/agents/ # 1b. 讀取本專案現有 .claude/ 狀態 ls .claude/ 2>/dev/null || echo "無 .claude/ 目錄" ls .claude/hooks/ 2>/dev/null cat .claude/settings.json 2>/dev/null # 1c. 讀取現有 CLAUDE.md cat CLAUDE.md 2>/dev/null # 1d. 確認分支策略 git log --oneline -5 git remote -v ``` --- ### Step 2 — 建立 .claude/ 結構 ```bash mkdir -p .claude/hooks mkdir -p .claude/agents ``` --- ### Step 3 — 複製全域 agents ```bash for f in ~/.claude/agents/*.md; do name=$(basename "$f") if [[ ! -f ".claude/agents/$name" ]]; then cp "$f" ".claude/agents/$name" echo "✅ agents/$name" else echo "⏭️ agents/$name 已存在，跳過" fi done ``` 若本專案有**專案專屬 agent**（如 db-expert.md），在此步驟後加入 `.claude/agents/`。 --- ### Step 4 — 建立三個設定檔 #### 4a. `.claude/hooks/branch-protection.local.json` 根據本專案分支策略選擇： ```bash # 選項 A：main 可直接 commit（push-to-deploy 模式，如 momo） echo '{"protectedBranches": ["production"]}' > .claude/hooks/branch-protection.local.json # 選項 B：main 受保護，必須開 feature branch echo '{"protectedBranches": ["main", "production"]}' > .claude/hooks/branch-protection.local.json ``` #### 4b. `.claude/hooks/secrets.local.json` 填入**本專案使用的 Token/Key 格式**，讓全域 commit-quality.js 自動載入： ```json [ {"pattern": "PATTERN_REGEX", "label": "Token 名稱"}, {"pattern": "ANOTHER_PATTERN", "label": "另一個 Token"} ] ``` 常見範例（按需選用）： ```json [ {"pattern": "\\d{8,12}:[A-Za-z0-9_-]{35}", "label": "Telegram Bot Token"}, {"pattern": "TELEGRAM[_\\s]*TOKEN\\s*=\\s*[\"']?[^\\s\"']{20,}", "label": "Telegram Token 環境變數"}, {"pattern": "glpat-[a-zA-Z0-9_-]{20}", "label": "Gitea/GitLab PAT"}, {"pattern": "GITEA[_\\s]*TOKEN\\s*=\\s*[\"']?[^\\s\"']{20,}", "label": "Gitea Token 環境變數"} ] ``` #### 4c. `.claude/settings.json` **如果本專案已有 settings.json**：讀完後手動合併，保留現有欄位，只更新 hooks 格式。 **如果本專案沒有 settings.json**：直接建立： ```json { "permissions": { "defaultMode": "bypassPermissions", "additionalDirectories": ["/tmp"] }, "hooks": { "PreToolUse": [ { "matcher": "", "hooks": [ {"type": "command", "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/-guard.js"}, {"type": "command", "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/large-file-warner.js"}, {"type": "command", "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/mcp-health.js"} ] } ], "PostToolUse": [ { "matcher": "", "hooks": [ {"type": "command", "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/audit-log.js"}, {"type": "command", "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/suggest-compact.js"} ] } ], "Stop": [ { "matcher": "", "hooks": [ {"type": "command", "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/cost-tracker.js"}, {"type": "command", "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/session-summary.js"} ] } ] } } ``` 注意： - `commit-quality.js` 不需列入（全域已跑） - `-guard.js` 是**本專案專屬的生產環境保護 hook**（見 Step 5） - `$CLAUDE_PROJECT_DIR` 是 Claude Code 自動注入的環境變數，指向專案根目錄 --- ### Step 5 — 建立專案 guard hook 參考 momo-prod-guard.js，為本專案寫一個 `-guard.js`。 **最小可用版本**（無任何阻擋，只稽核）： ```javascript // .claude/hooks/-guard.js const { spawnSync } = require('child_process'); let d = ''; process.stdin.on('data', c => d += c); process.stdin.on('end', () => { try { const i = JSON.parse(d); const cmd = String(i.tool_input?.command || ''); // 在此加入本專案需要阻擋的危險操作 // 參考: momo-prod-guard.js 的寫法 } catch (e) {} process.stdout.write(d); }); ``` **需要阻擋的常見危險操作**（按本專案需求選用）： - `docker compose down -v`（刪 volume） - `kubectl delete namespace` - `--remove-orphans`（如有多專案共存 Docker） - 直接操作 production DB --- ### Step 6 — 更新 CLAUDE.md **保留**本專案現有的所有專案索引（環境、服務、指令等）。 **移除**與全域重複的通用規則（P7/P9/P10、三紅線、委派表）——這些由 `~/.claude/CLAUDE.md` 自動 concatenate 補全。 **在檔案頂部加入一行**： ```markdown > 全域工作流程（P7/P9/P10、三紅線、委派表）見 `~/.claude/CLAUDE.md` ``` **在檔案底部加入安全架構說明**： ```markdown ## 安全架構（bypassPermissions） 本專案採用 `permissions.defaultMode: "bypassPermissions"` + Hook 自動政策。 | Hook | 觸發點 | 防護內容 | |------|--------|---------| | `-guard.js` | PreToolUse | 專案危險操作阻擋 | | `large-file-warner.js` | PreToolUse | >2MB 阻擋，>500KB 警告 | | `mcp-health.js` | PreToolUse | MCP 冷卻保護 | | `audit-log.js` | PostToolUse | Bash 指令稽核 | | `suggest-compact.js` | PostToolUse | 50 次工具呼叫後建議 /compact | | `cost-tracker.js` | Stop | Token 用量追蹤 | | `session-summary.js` | Stop | 對話快照存檔 | 全域 Hook（`~/.claude/hooks/`）同時生效：branch-protection / commit-quality / python-quality / yaml-validator ``` --- ### Step 7 — 驗證 & commit ```bash # 確認所有檔案就位 ls .claude/ ls .claude/hooks/ ls .claude/agents/ cat .claude/settings.json # 確認 .gitignore 有排除 settings.local.json grep "settings.local.json" .gitignore || echo ".claude/settings.local.json" >> .gitignore # Commit git add CLAUDE.md .claude/ .gitignore git status # 最後確認一次 git commit -m "feat(claude): 套用 ty-ai-standards Global-Local 架構" git push ``` --- ## 五、完成後的架構圖 ``` ~/.claude/ ← 全域層（所有專案共用） ├── CLAUDE.md ← P7/P9/P10 + 三紅線 + 委派表 ├── settings.json ← 全域 hooks 清單 ├── hooks/ ← 10 個通用 hooks（自動生效） └── agents/ ← 10 個通用 agents /.claude/ ← 本地層（本專案專屬） ├── settings.json ← bypassPermissions + 專案 hooks ├── agents/ ← 全域 agents 副本 + 專案特規 agent └── hooks/ ├── -guard.js ← 專案危險操作保護 ├── secrets.local.json ← 專案 Token pattern（全域 commit-quality 自動載入） └── branch-protection.local.json ← 分支保護覆蓋設定 ``` --- ## 六、判斷表：遇到衝突時 | 情況 | 做法 | |------|------| | 現有 settings.json 超大 | 讀清楚再合併，**不整個覆蓋** | | 現有 hooks 已有 shell 版本 | 保留，並列執行；或改寫成 `.js` 統一管理 | | CLAUDE.md 有大量專案規則 | **全部保留**，只加全域參照那一行，去掉通用重複段落 | | 專案用 main 直接 push | `branch-protection.local.json` → `{"protectedBranches": ["production"]}` | | 專案有 PR 審查流程 | `branch-protection.local.json` → `{"protectedBranches": ["main", "production"]}` | | 現有 secret hook 已掃某 pattern | 不需加入 secrets.local.json，避免雙重告警 | --- ## 七、完成判斷（DoD） - [ ] `~/.claude/` 全域架構確認存在（10 hooks + 10 agents） - [ ] `.claude/settings.json` 格式正確（`defaultMode: "bypassPermissions"` + 物件格式 hooks） - [ ] `.claude/hooks/secrets.local.json` 填入專案 Token pattern - [ ] `.claude/hooks/branch-protection.local.json` 設定符合分支策略 - [ ] `.claude/agents/` 有 10 個通用 agents（含專案特規 agent） - [ ] `CLAUDE.md` 加入全域參照、移除重複通用規則、加入安全架構說明 - [ ] `.gitignore` 含 `.claude/settings.local.json` - [ ] Commit 成功，push 成功