ewoooc/docs/guides/ty-ai-standards-onboarding.md

ty-ai-standards 新專案接入指令書

本文件由統帥產生，可直接轉發給負責新專案的 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 — 讀取現況（禁止跳過）

執行以下指令，全部讀完再開始動手：

# 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/ 結構

mkdir -p .claude/hooks
mkdir -p .claude/agents

---

Step 3 — 複製全域 agents

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

根據本專案分支策略選擇：

# 選項 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 自動載入：

[
  {"pattern": "PATTERN_REGEX", "label": "Token 名稱"},
  {"pattern": "ANOTHER_PATTERN", "label": "另一個 Token"}
]

常見範例（按需選用）：

[
  {"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：直接建立：

{
  "permissions": {
    "defaultMode": "bypassPermissions",
    "additionalDirectories": ["/tmp"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {"type": "command", "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/<project>-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 不需列入（全域已跑）
• <project>-guard.js 是本專案專屬的生產環境保護 hook（見 Step 5）
• $CLAUDE_PROJECT_DIR 是 Claude Code 自動注入的環境變數，指向專案根目錄

---

Step 5 — 建立專案 guard hook

參考 momo-prod-guard.js，為本專案寫一個 <project>-guard.js。

最小可用版本（無任何阻擋，只稽核）：

// .claude/hooks/<project>-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 補全。

在檔案頂部加入一行：

> 全域工作流程（P7/P9/P10、三紅線、委派表）見 `~/.claude/CLAUDE.md`

在檔案底部加入安全架構說明：

## 安全架構（bypassPermissions）

本專案採用 `permissions.defaultMode: "bypassPermissions"` + Hook 自動政策。

| Hook | 觸發點 | 防護內容 |
|------|--------|---------|
| `<project>-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

# 確認所有檔案就位
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

<project>/.claude/            ← 本地層（本專案專屬）
├── settings.json             ← bypassPermissions + 專案 hooks
├── agents/                   ← 全域 agents 副本 + 專案特規 agent
└── hooks/
    ├── <project>-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 成功