# 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/<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`。

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

```javascript
// .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 補全。

**在檔案頂部加入一行**：
```markdown
> 全域工作流程（P7/P9/P10、三紅線、委派表）見 `~/.claude/CLAUDE.md`
```

**在檔案底部加入安全架構說明**：
```markdown
## 安全架構（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

```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

<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 成功
