產生和維護 snapshot.json 專案地圖

version
1.1.0
GitHub stars
6

Install

/plugin install snapshot@claude-code-snapshot

Run it inside Claude Code after adding the marketplace with /plugin marketplace add cashwu/claude-code-snapshot.

Contents

Discovered from source

Commands 2

在 CLAUDE.md 加入 Snapshot 參考

你負責在專案的 CLAUDE.md 檔案中加入 snapshot 參考提示。

執行流程

Step 1: 檢查 CLAUDE.md

  1. 檢查專案根目錄是否有 CLAUDE.md 檔案
  2. 如果存在,讀取檔案內容

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 參考提示

注意事項

  1. 不要覆蓋 - 絕對不能覆蓋 CLAUDE.md 原有內容
  2. 避免重複 - 檢查關鍵字避免重複加入
  3. 保持格式 - 確保加入的內容前後有適當的空行

產生專案快照 (Snapshot)

產生精簡的專案快照,使用 TOON 格式節省 token。

TOON 格式說明

TOON (Token-Oriented Object Notation) 專為 LLM 優化,比 JSON 節省約 40% token。

語法規則:

  • 縮排表示巢狀結構
  • [N] 標示陣列長度
  • {field1,field2} 宣告欄位標題
  • 多值用 | 分隔
  • 空值直接留空

縮寫對照

縮寫原意縮寫原意
projprojectmmodules
descdescriptionrroutes
techtech_stackcfgconfig
langlanguagectrlcontrollers
fwframeworksvcservices
dbdatabasereporepositories
tpltemplatecmpcomponents
depsdependenciestbltable

執行流程

Step 1: 準備工作

  1. 檢查 .snapshot/ 目錄,不存在則建立
  2. 檢查現有 snapshot 檔案

Step 2: 架構偵測

專案類型偵測檔案
Java/Kotlin Multi-modulesettings.gradle(.kts) 含 include
.NET Multi-project*.sln 含多個 *.csproj
JS/TS Monorepopnpm-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

注意事項

  1. 精簡為主 - 只記錄重要模組
  2. 英文描述 - 用最短英文描述(省 token)
  3. 路由優先 - 優先記錄 URL→handler→db→template 對應

輸出

split輸出檔案
none.snapshot/snapshot.toon
projectsindex.toon + projects/*.toon
modulesindex.toon + modules/*.toon

Sponsors

Details

Marketplace
cashwu/claude-code-snapshot
Source
plugins/snapshot
Author
cash
Category
Productivity