
snapshot
產生和維護 snapshot.json 專案地圖
- version
- 1.1.0
- GitHub stars
- 6
Install
/plugin install snapshot@claude-code-snapshotRun it inside Claude Code after adding the marketplace with /plugin marketplace add cashwu/claude-code-snapshot.
Contents
Discovered from sourceCommands 2
在 CLAUDE.md 加入 Snapshot 參考
你負責在專案的 CLAUDE.md 檔案中加入 snapshot 參考提示。
執行流程
Step 1: 檢查 CLAUDE.md
- 檢查專案根目錄是否有
CLAUDE.md檔案 - 如果存在,讀取檔案內容
Step 2: 判斷是否需要加入
檢查檔案內容是否已包含 .snapshot/snapshot.json 字串:
- 已包含 → 輸出提示訊息,不做任何修改
- 未包含 → 繼續 Step 3
Step 3: 加入提示文字
如果 CLAUDE.md 不存在:
建立新檔案,內容為:
## 專案架構
如需了解專案架構,請參考 `.snapshot/snapshot.json`。
如果 CLAUDE.md 已存在:
在檔案最後加入(前面空一行):
## 專案架構
如需了解專案架構,請參考 `.snapshot/snapshot.json`。
Step 4: 輸出結果
成功加入時:
已在 CLAUDE.md 加入 snapshot 參考提示
已存在時:
CLAUDE.md 已包含 snapshot 參考,無需重複加入
建立新檔案時:
已建立 CLAUDE.md 並加入 snapshot 參考提示
注意事項
- 不要覆蓋 - 絕對不能覆蓋 CLAUDE.md 原有內容
- 避免重複 - 檢查關鍵字避免重複加入
- 保持格式 - 確保加入的內容前後有適當的空行
產生專案快照 (Snapshot)
產生精簡的專案快照,使用 TOON 格式節省 token。
TOON 格式說明
TOON (Token-Oriented Object Notation) 專為 LLM 優化,比 JSON 節省約 40% token。
語法規則:
- 縮排表示巢狀結構
[N]標示陣列長度{field1,field2}宣告欄位標題- 多值用
|分隔 - 空值直接留空
縮寫對照
| 縮寫 | 原意 | 縮寫 | 原意 |
|---|---|---|---|
| proj | project | m | modules |
| desc | description | r | routes |
| tech | tech_stack | cfg | config |
| lang | language | ctrl | controllers |
| fw | framework | svc | services |
| db | database | repo | repositories |
| tpl | template | cmp | components |
| deps | dependencies | tbl | table |
執行流程
Step 1: 準備工作
- 檢查
.snapshot/目錄,不存在則建立 - 檢查現有 snapshot 檔案
Step 2: 架構偵測
| 專案類型 | 偵測檔案 |
|---|---|
| Java/Kotlin Multi-module | settings.gradle(.kts) 含 include |
| .NET Multi-project | *.sln 含多個 *.csproj |
| JS/TS Monorepo | pnpm-workspace.yaml、lerna.json、workspaces |
決定 split:
projects: 多專案架構(2+ 子專案)modules: 大型專案(50+ 模組)none: 一般專案
Step 3: 掃描專案
掃描重點
- 識別路由對應(URL→handler→db→template)
- 識別模組及相依性
- 找出 Entry point
忽略目錄
node_modules/, vendor/, build/, dist/, .git/, .snapshot/, __pycache__/, .idea/, coverage/
Step 4: 產生 Snapshot
模式 A: split: none
產生 .snapshot/snapshot.toon:
proj: project-name
desc: short desc
v: 1.0
ts: 2025-01-01T00:00:00Z
split: none
tech:
lang: TypeScript
fw: Next.js
db: PostgreSQL
entry: src/app/layout.tsx
r[6]{route,handler,tables,tpl}:
GET /,page.tsx,,RootLayout
GET /users,UserPage,users,UserList
GET /users/:id,UserDetailPage,users|profiles,UserDetail
POST /api/users,UserCtrl.create,users,
PUT /api/users/:id,UserCtrl.update,users,
DELETE /api/users/:id,UserCtrl.delete,users,
m.ctrl[2]{name,path,desc,deps}:
UserCtrl,src/ctrl/user.ts,user api,UserSvc
ProductCtrl,src/ctrl/product.ts,product api,ProductSvc
m.svc[2]{name,path,desc,deps}:
UserSvc,src/svc/user.ts,user logic,UserRepo|EmailSvc
ProductSvc,src/svc/product.ts,product logic,ProductRepo
m.repo[2]{name,path,desc,deps}:
UserRepo,src/repo/user.ts,users tbl,
ProductRepo,src/repo/product.ts,products tbl,
m.cmp[2]{name,path,desc,deps}:
UserList,src/cmp/UserList.tsx,user list ui,
UserDetail,src/cmp/UserDetail.tsx,user detail ui,
cfg[3]: package.json,tsconfig.json,.env
patterns[2]: Repository,MVC
模式 B: split: projects
.snapshot/
├── index.toon
└── projects/
├── project-a.toon
└── project-b.toon
index.toon:
proj: project-name
desc: short desc
v: 1.0
ts: 2025-01-01T00:00:00Z
split: projects
tech:
lang: Java
fw: Spring Boot
subs[2]{name,file,dir,desc}:
project-a,projects/project-a.toon,project-a/,sub-project A
project-b,projects/project-b.toon,project-b/,sub-project B
cfg[1]: settings.gradle
projects/project-a.toon:
proj: project-a
parent: parent-proj
desc: sub-project desc
tech:
lang: Java
fw: Spring Boot
entry: src/main/java/App.java
r[2]{route,handler,tables,tpl}:
GET /api/users,UserCtrl.list,users,
POST /api/users,UserCtrl.create,users,
m.ctrl[1]{name,path,desc,deps}:
UserCtrl,src/ctrl/UserCtrl.java,user api,UserSvc
m.svc[1]{name,path,desc,deps}:
UserSvc,src/svc/UserSvc.java,user logic,UserRepo
m.repo[1]{name,path,desc,deps}:
UserRepo,src/repo/UserRepo.java,users tbl,
cfg[1]: build.gradle
模式 C: split: modules
.snapshot/
├── index.toon
└── modules/
├── ctrl.toon
├── svc.toon
└── repo.toon
index.toon:
proj: project-name
desc: short desc
v: 1.0
ts: 2025-01-01T00:00:00Z
split: modules
tech:
lang: Java
fw: Spring Boot
db: MySQL
entry: src/main/java/App.java
r[3]{route,handler,tables,tpl}:
GET /api/users,UserCtrl.list,users,
POST /api/users,UserCtrl.create,users,
GET /api/products,ProductCtrl.list,products,
mIdx[3]{type,file,count}:
ctrl,modules/ctrl.toon,25
svc,modules/svc.toon,30
repo,modules/repo.toon,20
cfg[1]: application.yml
patterns[2]: Repository,Service
modules/ctrl.toon:
type: ctrl
parent: project-name
items[2]{name,path,desc,deps}:
UserCtrl,src/ctrl/UserCtrl.java,user api,UserSvc
ProductCtrl,src/ctrl/ProductCtrl.java,product api,ProductSvc
Step 5: 顯示摘要
## Snapshot 產生完成
📁 .snapshot/snapshot.toon
- routes: X
- modules: X
注意事項
- 精簡為主 - 只記錄重要模組
- 英文描述 - 用最短英文描述(省 token)
- 路由優先 - 優先記錄 URL→handler→db→template 對應
輸出
| split | 輸出檔案 |
|---|---|
| none | .snapshot/snapshot.toon |
| projects | index.toon + projects/*.toon |
| modules | index.toon + modules/*.toon |
Sponsors
Details
- Marketplace
- cashwu/claude-code-snapshot
- Source
- plugins/snapshot
- Author
- cash
- Category
- Productivity