309 lines
10 KiB
Markdown
309 lines
10 KiB
Markdown
# 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 成功
|