把 kickstart 分成 3 層：
CLAUDE.md：永遠要知道的專案原則，例如命名、架構分層、測試、禁止事項。Claude 官方建議 CLAUDE.md 放專案慣例、build/test 指令與架構規則，而且最好維持精簡，約 200 行以內。(Claude Code)
Skills：可重複觸發的工作流，例如「架構掃描」、「命名審查」、「依存圖分析」、「PR 前變更影響分析」。專案 skills 放在
.claude/skills/<skill-name>/SKILL.md。(Claude Code)Agents / Subagents：隔離上下文的專家角色，例如 architecture-reviewer、naming-auditor、dependency-mapper。專案 subagents 放在
.claude/agents/，也可以用/agents互動建立。(Claude Code)
0. 在 VS Code terminal 進入專案
cd /path/to/your-project
code .
claude
進入 Claude Code 後，先跑官方初始化：
/init
如果你想用新版互動式 init，官方文件提到可以先設：
CLAUDE_CODE_NEW_INIT=1 claude
然後在 Claude Code 裡跑：
/init
新版 /init 會詢問要不要建立 CLAUDE.md、skills、hooks，並用 subagent 探索 codebase 後提出可審查方案。(Claude Code)
1. 直接丟給 Claude 的 kickstart 指令
在 Claude Code 裡貼這段：
請用 first principles 幫這個專案建立「Codebase Intelligence / 架構透視」工作流。
目標：
1. 更新或建立 CLAUDE.md
2. 建立 .claude/rules/
3. 建立 .claude/skills/
4. 建立 .claude/agents/
5. 不要直接重構產品程式碼，先只建立 AI 協作規範與分析工具
請先掃描目前專案：
- 語言、框架、package manager
- build / test / lint 指令
- src / tests / docs / config 結構
- 主要 entrypoints
- API / service / domain / data / UI 層
- 目前命名風格
- 依存與架構風險
然後產生以下檔案：
1. CLAUDE.md
內容包含：
- Project overview
- Build / test / lint commands
- Architecture principles
- Naming rules
- Dependency rules
- Code readability rules
- Change impact workflow
- Security rules
- Before editing checklist
- Before commit checklist
2. .claude/rules/architecture.md
規範 layer boundary、允許/禁止依存、核心流程如何維護。
3. .claude/rules/naming.md
規範檔案、函式、class、boolean、event、API route、test 命名。
4. .claude/rules/testing.md
規範何時要加 unit / integration / e2e tests，以及測試命名。
5. .claude/skills/architecture-scan/SKILL.md
建立一個 /architecture-scan skill，用來掃描專案結構、核心流程、依存風險與架構層級。
6. .claude/skills/naming-review/SKILL.md
建立一個 /naming-review skill，用來檢查命名是否清楚、是否符合 domain language、是否有 helper/utils/manager/common 等模糊名稱。
7. .claude/skills/dependency-map/SKILL.md
建立一個 /dependency-map skill，用來分析 import graph、fan-in、fan-out、circular dependency、cross-layer violation。
8. .claude/skills/change-impact/SKILL.md
建立一個 /change-impact skill，用來在修改前或 PR 前分析變更影響、測試需求、文件更新需求與風險。
9. .claude/agents/architecture-reviewer.md
建立專案專用 subagent，負責架構分層、依存方向、模組責任邊界審查。
10. .claude/agents/naming-auditor.md
建立專案專用 subagent，負責命名一致性、domain language、可讀性與 code smell 審查。
11. .claude/agents/dependency-mapper.md
建立專案專用 subagent，負責依存圖、循環依賴、高風險節點、變更影響分析。
要求：
- 先提出檔案清單與內容摘要給我確認
- 不要改產品程式碼
- 每個 skill 的 SKILL.md 要有 YAML frontmatter
- 每個 agent 要有 YAML frontmatter
- CLAUDE.md 保持精簡，不要超過 200 行
- 詳細規則放進 .claude/rules/ 或 skills
- 所有規則都要可操作、可檢查，不要寫空泛原則
2. 如果你想讓 Claude 直接建立檔案，可以用這版
請直接建立或更新以下 Claude Code 專案配置檔案，不要修改產品程式碼：
- CLAUDE.md
- .claude/rules/architecture.md
- .claude/rules/naming.md
- .claude/rules/testing.md
- .claude/skills/architecture-scan/SKILL.md
- .claude/skills/naming-review/SKILL.md
- .claude/skills/dependency-map/SKILL.md
- .claude/skills/change-impact/SKILL.md
- .claude/agents/architecture-reviewer.md
- .claude/agents/naming-auditor.md
- .claude/agents/dependency-mapper.md
請先讀取 README、package files、src、tests、config，但不要執行不明 shell script。
設計原則：
- CLAUDE.md 只放永遠需要的規則
- .claude/rules/ 放可長期套用的分層、命名、測試規範
- skills 放可手動觸發的分析工作流
- agents 放隔離上下文的專家 reviewer
- 所有內容都要以 first principles 解釋：entity、relation、responsibility、layer、flow、change impact
- 所有 skill 和 agent 都要能被其他專案複製後調整使用
3. 建好後可以跑的 Claude 指令
/architecture-scan
用途：建立專案地圖，找出主要 entrypoints、核心流程、層級、風險。
/naming-review src
用途：檢查 src 下面是否有模糊命名、domain language 不一致、責任不清。
/dependency-map
用途：找 circular dependency、跨層依賴、高 fan-in / fan-out 模組。
/change-impact
用途：在修改前或 PR 前分析目前 git diff 可能影響哪些模組、測試與文件。
/agents
用途：打開 Claude Code 的 subagent 管理介面。官方文件說 /agents 可以查看、建立、編輯、刪除 custom subagents。(Claude Code)
4. 建議的最小 CLAUDE.md 內容方向
你可以要求 Claude 照這個骨架產生：
# Project Instructions for Claude Code
## Project Goal
Explain what this project does in 3-5 lines.
## Commands
- Install:
- Dev:
- Build:
- Test:
- Lint:
- Typecheck:
## Architecture Principles
- Keep responsibilities explicit.
- Separate UI/API/application/domain/data/infrastructure layers.
- Do not introduce cross-layer dependencies without explaining why.
- Prefer small modules with clear input/output contracts.
## Naming Principles
- Names must reveal purpose, responsibility, and domain meaning.
- Avoid vague names such as helper, utils, common, manager, processor unless narrowly scoped.
- Functions should start with verbs.
- Booleans should read like questions: is/has/can/should/requires.
- Events should describe something that already happened.
## Dependency Rules
- UI must not directly depend on data access.
- Domain logic must not depend on framework-specific APIs.
- Utility modules must not import application services.
- Avoid circular dependencies.
## Change Workflow
Before editing:
1. Identify affected entities.
2. Identify upstream and downstream dependencies.
3. Check related tests.
4. Check whether docs or rules need updates.
Before commit:
1. Run relevant tests.
2. Run lint/typecheck if available.
3. Summarize changed nodes and impact.
4. Flag unresolved risk.
5. 建議建立的 skill 範本
例如 .claude/skills/change-impact/SKILL.md 可以長這樣：
---
name: change-impact
description: Analyze git diff or planned changes for architectural, dependency, testing, and documentation impact before implementation or PR.
disable-model-invocation: true
allowed-tools: Read Grep Glob Bash
---
# Change Impact Analysis
Use this skill when the user asks to evaluate a planned change, current git diff, or PR readiness.
## Steps
1. Inspect the current diff:
- Prefer `git diff --stat`
- Then inspect relevant files with `git diff`
- Do not modify files
2. Identify changed entities:
- files
- functions
- classes/types
- API routes
- data models
- tests
- docs/config
3. Map dependencies:
- who imports changed files
- who calls changed functions
- which tests cover them
- which flows may be affected
4. Evaluate risk:
- low: isolated implementation detail
- medium: shared module or API behavior
- high: auth, payment, data migration, permissions, public API, core domain
- critical: security, data loss, production infrastructure
5. Output:
- Summary
- Changed nodes
- Upstream/downstream impact
- Tests to run
- Docs to update
- Risks and recommended next steps
這裡的 disable-model-invocation: true 適合用在你想手動觸發的工作流。Claude 官方文件說 skills 可以讓 Claude 自動選用，也可以用這個 frontmatter 讓它只在你手動 /skill-name 時啟用。(Claude Code)
6. 建議建立的 agent 範本
例如 .claude/agents/architecture-reviewer.md：
---
name: architecture-reviewer
description: Reviews architecture boundaries, module responsibilities, dependency direction, and change impact.
tools: Read, Glob, Grep, Bash
model: sonnet
---
You are an architecture reviewer for this repository.
Your job is to inspect code structure, not to rewrite code unless explicitly asked.
Review using first principles:
1. Entities
- What files, modules, functions, classes, APIs, models, jobs, and tests are involved?
2. Relationships
- What imports what?
- What calls what?
- What reads/writes data?
- What flow does this participate in?
3. Responsibilities
- Does each module have one clear reason to change?
- Are names aligned with actual responsibility?
4. Layers
- Identify UI, API, application, domain, data, infrastructure, utility, and test layers.
- Flag cross-layer dependency violations.
5. Change impact
- Identify upstream and downstream impact.
- Recommend tests and docs to update.
Output format:
- Architecture summary
- Boundary issues
- Dependency risks
- Naming or responsibility issues
- Suggested refactor options
- Risk level
Subagents 適合這種會讀很多檔案、但你不想污染主對話上下文的工作。官方文件也把 subagents 定位成 isolated execution context，會回傳摘要。(Claude Code)
7. 我會推薦你的實際 kickstart 順序
在 VS Code terminal：
cd your-project
CLAUDE_CODE_NEW_INIT=1 claude
在 Claude Code 裡：
/init
然後貼：
請用 first principles 更新 CLAUDE.md，並建立 architecture、naming、testing rules，以及 architecture-scan、naming-review、dependency-map、change-impact 四個 skills，另外建立 architecture-reviewer、naming-auditor、dependency-mapper 三個 project subagents。先提出方案，不要改產品程式碼。
確認方案後再說：
可以，請建立這些 Claude Code 配置檔案。只允許修改 CLAUDE.md 與 .claude/ 目錄，不要修改 src、tests、package files 或產品程式碼。
建好後馬上跑：
/architecture-scan
/dependency-map
/naming-review src
/change-impact
這樣你的專案就會從「Claude 只是幫你寫 code」升級成「Claude 先維護一套可理解、可審查、可演進的專案知識系統」。
沒有留言:
張貼留言