CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Claude Code 插件市场（marketplace），通过 三条任务入口（需求 / Bug / 调整）→ 计划 → 执行 → 提交 → 文档更新 的标准化流程，把人工审核与 AI 自动化结合。本仓库是 Markdown 技能定义 + Python 脚本辅助，无构建/测试/ lint 配置。

插件体系

插件	定位	技术体系
`commons`	公共流程：需求 / Bug / 调整三条入口 + 执行提交流程 + 组件索引重建	通用
`frontend`	write-design / write-design-plan / write-architecture / write-components（自有 + 三方统一）/ write-bugfix-plan / write-change-plan	pnpm monorepo / TypeScript
`backend`	write-design / write-design-plan / write-architecture / write-components（自有 + 三方统一）/ write-bugfix-plan / write-change-plan	Maven 多模块 / Java

安装规则：前端项目装 commons + frontend，后端项目装 commons + backend。

⚠ frontend 与 backend 互斥：两者定义了同名 skill（write-design 等 6 个），同时安装会导致命令调用歧义。务必只装其一。

元数据文件

marketplace.json（仓库根 `.claude-plugin/`）

注册市场本身及包含的插件列表。包含 name、description、version、owner（name + email）和 plugins 数组。每个插件条目需要 name、description、source（相对路径）、version。

plugin.json（插件 `.claude-plugin/`）

每个插件目录下需要 name、version、description。新增插件时两个文件都要同步更新。

插件目录结构规范

plugin-name/
├── .claude-plugin/
│   └── plugin.json
├── scripts/              # 可选，按需创建；插件级脚本（由 hooks 或多个 SKILL 共享）
│   └── *.py
├── hooks/                # 可选，按需创建
│   └── hooks.json
└── skills/
    └── <skill-name>/
        ├── SKILL.md         # YAML 头部 + 执行步骤
        ├── templates/       # 输出文档模板（仅编写 docs 的 skill）
        │   └── template.md
        ├── scripts/         # SKILL 级脚本（仅该 SKILL 使用，Python，仅标准库）
        │   └── *.py
        └── references/      # 可选，使用手册等参考资料

SKILL.md 规范

YAML 头部字段：

字段	说明
`name`	技能名称，调用方式 `/name`
`description`	帮助信息中的简短描述
`argument-hint`	CLI 风格参数提示
`allowed-tools`	技能执行期间允许的工具列表
`model`	`haiku` / `sonnet` / `opus`
`disable-model-invocation`	必填 `true`——禁止模型自动 routing，仅允许用户显式 `/skill-name` 触发。本仓库全部 SKILL 都需启用

引用模板统一使用相对路径 markdown link：[./templates/template.md](./templates/template.md)。引用脚本同样用相对 markdown link：[./scripts/foo.py](./scripts/foo.py)，SKILL 中通过 ${CLAUDE_PLUGIN_ROOT} 定位脚本路径后 Bash 直接 python3 执行（详见下方"脚本化优先"）。

前后端同名的 skill（如 write-design、write-design-plan）需分别维护各自的 SKILL.md 和 template.md，内容针对各自技术栈。

新增 SKILL 必做项（写文档类）

新增 write-* / generate-* 类 SKILL 时按顺序检查（执行类 execute-plan / commit-work / cleanup-worktree / rebuild-components-index 不适用本清单）：

plugins/<plugin>/.claude-plugin/plugin.json：插件级元数据，新增 SKILL 不需改（plugin.json 不列 skills）
SKILL.md YAML 头 allowed-tools 必须含 git——守卫块依赖 git rev-parse，常用形式 Bash(ls, mkdir, git) 或全开 Bash
SKILL.md 第 0 步插入 worktree 守卫块（与现有 SKILL 完全一致的代码片段，对比 git rev-parse --git-dir 与 --git-common-dir）
模板用相对 markdown link 引用：[./templates/template.md](./templates/template.md)
Bash 命令路径统一相对仓库根：每条 Bash 开头 cd "$(git rev-parse --show-toplevel)"
若属"指令可控依赖"范畴（架构识别 / 计划 / bugfix / change），调用 pnpm 或 mvn 指令，不仅凭文件名推断
输出文档落到 docs/ 平铺存储，命名遵循 {code}-{name} / {module} / 组件命名脚本等现有规范
若属 write-* 文档类，统一支持两种调用模式：
- 新建模式：第一参数为 {编码} / {module} / package 等，按既有约定生成
- 调整模式：第一参数为已存在的目标 .md 文件名，第二参数为自由文本调整意见；按"幂等合并原则"应用，意见原文记入「变更说明」段；意见与事实冲突时诚实记录"未采纳"
若属 generate-* 入口类，统一支持两种调用模式：
- 新建模式：参数为自由文本描述。AI 读取 docs/components/index.md + docs/architecture/*.md 预填充"关键要点"章节（涉及模块、关联组件、影响范围），不确定时保留 {待人工补充} 占位符，不硬塞
- 补充模式：第一参数为6位纯数字编码，后续文本为补充描述。跨 requirements/bugs/changes 三目录定位文档；合并策略：保留已有内容 → 优先替换 {待人工补充} 占位符 → 无法对应时追加到「备注」章节
README.md「全部技能一览」表新增一行；如属前后端同名 skill，前端表与后端表各加一行

三条工作流

需求: /generate-requirement → 人工补充
  → /write-design {code} → 人工审核
    → /write-design-plan {code} → 人工审核
      → /execute-plan {code} → 人工测试
        → /commit-work {code}（worktree 内提交代码）
          → 退出 worktree 回到主仓库（当前分支即可）
            → /write-architecture（按需）→ /write-components {module} {组件}（按需，自动重建索引）
              → 主仓库当前分支独立 commit + push 文档
                → /cleanup-worktree {code}

Bug:  /generate-bug → 人工补充
  → /write-bugfix-plan {code} → 人工审核
    → /execute-plan {code} → 人工回归验证
      → /commit-work {code}（worktree 内提交代码）
        → 退出 worktree 回到主仓库（当前分支即可）
          → /write-architecture（按需）→ /write-components {module} {组件}（按需，自动重建索引）
            → 主仓库当前分支独立 commit + push 文档
              → /cleanup-worktree {code}

调整: /generate-change → 人工补充
  → /write-change-plan {code} → 人工审核
    → /execute-plan {code} → 人工验证
      → /commit-work {code}（worktree 内提交代码）
        → 退出 worktree 回到主仓库（当前分支即可）
          → /write-architecture（按需）→ /write-components {module} {组件}（按需，自动重建索引）
            → 主仓库当前分支独立 commit + push 文档
              → /cleanup-worktree {code}

每步需人工审核，AI 绝不自动提交。三条流程在 execute-plan 阶段汇聚。

代码与文档是两步独立提交：代码改动在 worktree 内通过 commit-work 提交，文档改动回到主仓库工作区独立 commit + push，不强制同分支同 commit。

任何 write-* 都同时接受"调整入口"，例如：/write-design-plan {编码}-design-{名称}.md 调整XXX，因为XXX，对既有文档做局部修订，详见各 SKILL 的"调用模式"段。

编码一致性

6 位数字编码在 requirements / bugs / changes 三个命名空间中全局唯一，贯穿全链路：

requirements/{code}-{name}.md → design/{code}-{name}.md → plan/{code}-design-{name}.md
bugs/{code}-{name}.md → plan/{code}-bugfix-{name}.md
changes/{code}-{name}.md → plan/{code}-change-{name}.md
最终 → branch/{code}-{name} → worktree/{code}-{name}

模型策略

opus（强模型）：write-design、write-design-plan、write-bugfix-plan、write-change-plan、write-architecture、write-components
haiku（轻模型）：generate-requirement、generate-bug、generate-change、execute-plan、commit-work、cleanup-worktree、rebuild-components-index

核心原则

文档编写位置约束

所有 write-* 与 generate-* 系列 SKILL 必须在主仓库工作区调用，不在 worktree 下运行。SKILL 内置硬守卫（git rev-parse --git-dir ≠ --git-common-dir 即 worktree）会拒绝执行。rebuild-components-index 同样适用。

本地分支由用户当下决定，SKILL 不强制——切到哪条分支就在那条分支的 docs/ 上落盘
代码（worktree）与文档（主仓库）是两步独立 commit，不强制合并到同一 commit
详见 README "文档编写位置约束" 章节

指令可控依赖

涉及模块识别、依赖分析的 skill 必须调用构建工具指令获取权威结果，不得仅凭文件名或配置文件推断：

前端：pnpm -r list、pnpm -F <pkg> list、pnpm why <pkg>
后端：mvn help:evaluate、mvn -pl <m> dependency:tree、mvn dependency:tree -Dincludes=...

适用 skill：write-architecture、write-design-plan、write-bugfix-plan、write-change-plan

注：write-components 由用户显式传入 {module} {组件}，不再走 git diff 自动扫描；前端额外强制校验该组件已在 package 入口 export（未导出直接终止），后端用 mvn help:evaluate 校验 module 在 workspace 内可解析。

脚本化优先（"指令可控依赖"在文档侧的延伸）

凡是可以被脚本化的逻辑（文件名计算、索引扫描重建、固定格式解析、跨文件元数据提取等）一律落到脚本文件，不允许 SKILL prompt 自己分析推导。脚本分两层：

插件级（plugins/<plugin>/scripts/*.py）：由 hooks 或多个 SKILL 共享的脚本，如 rebuild_components_index.py（frontend / backend 持有插件级副本；commons 的权威副本位于其 rebuild-components-index SKILL 级目录）
SKILL 级（plugins/<plugin>/skills/<skill>/scripts/*.py）：仅单一 SKILL 使用的脚本，如 component_filename.py
语言：统一 Python 3，仅依赖标准库（无第三方包），保证 macOS / Linux / Windows 跨平台行为一致
调用方式：SKILL.md 用 [./scripts/foo.py](./scripts/foo.py) 相对链接引用脚本；执行时通过 ${CLAUDE_PLUGIN_ROOT} 定位脚本路径，Bash 直接 python3 执行
唯一事实来源：脚本即规则。SKILL 不允许重复实现脚本逻辑（如自己拼接文件名、自己扫描目录、自己解析 metadata），重复实现会被列入校验 grep
跨 SKILL 共享：因 /plugin install 后插件目录不连通，需共享逻辑的脚本（如 component_filename.py）在每个消费 SKILL 下持有同名同内容副本；rebuild_components_index.py 以 commons SKILL 级副本为事实来源，frontend / backend 在各自插件级 scripts/ 持有副本；副本一致性由日常验证 grep 兜底

三方组件本地分析

write-components 的三方分支 API 信息 必须基于项目实际依赖的本地代码分析（前端读 node_modules/ 下的 .d.ts / .tsx，后端读 Maven 源码 jar），不允许使用 WebSearch / WebFetch。不同版本 API 差异大，文档必须与项目实际版本一致。源码 jar 不可用时直接终止，不允许基于 class 元信息或网上文档推断。

组件索引（docs/components/index.md）

docs/components/index.md 是下游 SKILL（write-design / write-design-plan / write-bugfix-plan / write-change-plan）查阅"项目里有哪些组件可用"的唯一入口：

由 /rebuild-components-index 维护；plugins/{frontend,backend}/hooks/hooks.json 定义了 PostToolUse hook，组件文档写入后自动触发重建脚本
表格列：组件模块 | 组件名称 | 组件描述（应用场景） | 文档地址
"组件描述"优先从文档 YAML frontmatter description 字段提取；frontmatter 缺失时 fallback 到 ## 何时使用 段首句
下游 SKILL 禁止全量扫描 docs/components/*.md，必须先读 index.md 选出相关条目，再选读详情

docs/ 扁平存储

所有 docs/ 子目录下 只允许平铺 .md，禁止嵌套子目录：

子目录	文件命名	内容
`requirements/`	`{code}-{name}.md`	需求
`bugs/`	`{code}-{name}.md`	Bug 反馈
`changes/`	`{code}-{name}.md`	调整任务
`design/`	`{code}-{name}.md`	详细设计（仅需求流程）
`plan/`	`{code}-{source}-{name}.md`	实施计划（source = design / bugfix / change）
`architecture/`	`{module}.md`	架构文档，与代码模块一一对应
`components/`	`{module}_{组件}.md` + `index.md`	组件文档（命名脚本计算）+ 自动维护的索引
`todo/`	`index.md`	任务安排（人工维护）

开发约束

前端

pnpm workspace monorepo + TypeScript
只有 package 入口 index.ts 中 export 的组件才算公共组件

后端

Maven 多模块 + Java
公共组件无强制命名前缀；能在当前 Maven workspace 解析到的 artifact 都允许编写组件文档（业务模块通常不写，但不被 SKILL 拒绝）

组件判定 + 文件命名

write-components 是强参形式 /write-components {module} {组件}（或调整模式 /write-components {文件名}.md {调整意见}），自有 + 三方统一处理，SKILL 自动判定来源：

前端：先 pnpm -F {module} list 校验 workspace 内（SOURCE=local，走 export 校验 + 源码分析）；失败时回退检查 node_modules/{module}/（SOURCE=third-party，跳过 export 校验，分析 .d.ts）
后端：先 mvn help:evaluate -pl {module} 校验 workspace 内（SOURCE=local，分析 src/main/java/）；失败时检查项目 pom 是否声明该依赖（SOURCE=third-party，mvn dependency:sources 拉源码 jar 解压分析；源码不可用直接终止）
文件命名：{module 中的 ':' 和 '/' 替换为 '__'}_{组件}.md，由 scripts/component_filename.py 计算（前后端 + commons 各持一份相同副本）；SKILL 禁止自行拼接
- @cloudbase:js-sdk demo → @cloudbase__js-sdk_demo.md
- flow-engine-framework GroovyScriptBind → flow-engine-framework_GroovyScriptBind.md
- antd Button → antd_Button.md
自有 + 三方共用 docs/components/ 扁平命名空间，文件名规则已嵌入 module 故同名组件不再撞名；写入前 SKILL 仍用文档头 metadata（来源 / 所属 module）做兜底冲突检测
组件文档写入后由插件级 PostToolUse hook 自动调用 rebuild_components_index.py 重建 docs/components/index.md（hooks/hooks.json）
分析以指定类/组件为锚点，但要扩展到其依赖与紧密相关的对外 API（子组件、配置类、工具类、SPI 注解、Hook 等），呈现"组件整体"
三方分支必须基于本地依赖代码分析 API，禁用 WebSearch / WebFetch

日常验证命令

本仓库无 build / lint / test 配置，但有一组 grep / diff 校验在改 SKILL / 文档时反复用到，作为开发循环的回归手段：

# 1) 守卫块覆盖：所有写文档 + 索引 SKILL 必须命中 GIT_COMMON
grep -L "GIT_COMMON" \
  plugins/commons/skills/{generate-*,rebuild-components-index}/SKILL.md \
  plugins/{frontend,backend}/skills/write-*/SKILL.md
# ↑ 期望输出为空；任何文件被列出说明守卫块缺失

# 2) allowed-tools 必须满足 (a) Bash 全开（无括号约束）或 (b) Bash(...) 白名单含 git
grep "allowed-tools" \
  plugins/commons/skills/{generate-*,rebuild-components-index}/SKILL.md \
  plugins/{frontend,backend}/skills/write-*/SKILL.md \
  | grep -vE 'Bash[],]|Bash\([^)]*git'
# ↑ 期望输出为空（有输出才说明违规；`grep -v` 无匹配时 exit code=1 是正常通过状态）
# ↑ 两种合法形式：Bash（全开，会匹配 "Bash," 或 "Bash]"）/ Bash(... git ...)（白名单含 git）

# 3) 幂等写入步骤覆盖：write-* SKILL 必须含「幂等合并原则」
grep -L "幂等合并原则" \
  plugins/{frontend,backend}/skills/write-{design,design-plan,architecture,components,bugfix-plan,change-plan}/SKILL.md
# ↑ 期望输出为空

# 4) 调整模式覆盖：所有 write-* SKILL 必须包含调整模式说明
grep -L "调整模式\|调整意见" \
  plugins/{frontend,backend}/skills/write-{design,design-plan,architecture,components,bugfix-plan,change-plan}/SKILL.md
# ↑ 期望输出为空

# 5) component_filename.py 副本一致性（commons 是事实来源）
diff plugins/commons/skills/rebuild-components-index/scripts/component_filename.py \
     plugins/frontend/skills/write-components/scripts/component_filename.py && \
diff plugins/commons/skills/rebuild-components-index/scripts/component_filename.py \
     plugins/backend/skills/write-components/scripts/component_filename.py
# ↑ 两次 diff 都应无输出（三份必须完全相同）

# 6) rebuild_components_index.py 副本一致性（commons 是事实来源，frontend/backend 在插件级 scripts/ 持有副本）
diff plugins/commons/skills/rebuild-components-index/scripts/rebuild_components_index.py \
     plugins/frontend/scripts/rebuild_components_index.py && \
diff plugins/commons/skills/rebuild-components-index/scripts/rebuild_components_index.py \
     plugins/backend/scripts/rebuild_components_index.py
# ↑ 两次 diff 都应无输出

# 7) 插件级 hooks.json 必须存在且引用 rebuild 脚本
ls plugins/{frontend,backend}/hooks/hooks.json
# ↑ 两文件都应存在
grep -L "rebuild_components_index" \
  plugins/{frontend,backend}/hooks/hooks.json
# ↑ 期望输出为空（hooks.json 中必须引用 rebuild 脚本）

# 8) 下游 SKILL 必须先读 components/index.md，禁止全量扫
grep -L "components/index.md" \
  plugins/{frontend,backend}/skills/write-{design,design-plan,bugfix-plan,change-plan}/SKILL.md
# ↑ 期望输出为空

# 9) 命名脚本必须被 write-components 引用
grep -L "component_filename.py" \
  plugins/{frontend,backend}/skills/write-components/SKILL.md
# ↑ 期望输出为空

九条命令通过 = 守卫覆盖、白名单一致性、幂等写入、调整模式、脚本副本同步、hooks 配置、组件索引接入都成立，相当于本仓库的"测试套件"。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

CLAUDE.md

Project Overview

插件体系

元数据文件

marketplace.json（仓库根 `.claude-plugin/`）

plugin.json（插件 `.claude-plugin/`）

插件目录结构规范

SKILL.md 规范

新增 SKILL 必做项（写文档类）

三条工作流

编码一致性

模型策略

核心原则

文档编写位置约束

指令可控依赖

脚本化优先（"指令可控依赖"在文档侧的延伸）

三方组件本地分析

组件索引（docs/components/index.md）

docs/ 扁平存储

开发约束

前端

后端

组件判定 + 文件命名

日常验证命令

Uh oh!

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

CLAUDE.md

Project Overview

插件体系

元数据文件

marketplace.json（仓库根 .claude-plugin/）

plugin.json（插件 .claude-plugin/）

插件目录结构规范

SKILL.md 规范

新增 SKILL 必做项（写文档类）

三条工作流

编码一致性

模型策略

核心原则

文档编写位置约束

指令可控依赖

脚本化优先（"指令可控依赖"在文档侧的延伸）

三方组件本地分析

组件索引（docs/components/index.md）

docs/ 扁平存储

开发约束

前端

后端

组件判定 + 文件命名

日常验证命令

marketplace.json（仓库根 `.claude-plugin/`）

plugin.json（插件 `.claude-plugin/`）