| name | write-project-context |
| description | 分析项目代码结构，生成一份 CLAUDE.md 项目架构文档，包含技术栈、目录结构、入口文件、架构模式和配置说明。当用户要求"生成 CLAUDE.md"、"写项目文档"、"分析项目架构"、"初始化项目上下文"时触发。 |
| allowed-tools | Read(*), Bash(ls:*, find:*, cat:*, head:*, tail:*), Write(*), Edit(*), Glob(*) |
| metadata | {"author":"tangjiahui","version":"1.0.0"} |
Write Project Context
分析当前项目的代码结构和架构模式，生成一份标准化的 CLAUDE.md 项目文档。
触发条件
当用户提到以下内容时调用此 skill：
- "生成/写/创建 CLAUDE.md"
- "写项目文档/项目上下文"
- "分析项目架构"
- "初始化项目"
- "帮我了解这个项目"
文档结构
生成的 CLAUDE.md 必须包含以下章节，按顺序排列：
┌──────────────────────────────────────┐
│ 项目概述（必选） │ 项目名称、简介、核心功能
├──────────────────────────────────────┤
│ 技术栈（必选） │ 运行时、框架、UI库、状态管理、构建工具等
├──────────────────────────────────────┤
│ 目录结构（必选） │ src/ 下的完整目录树 + 各目录职责说明
├──────────────────────────────────────┤
│ 入口文件（必选） │ main.tsx → Router → Pages 的启动链路
├──────────────────────────────────────┤
│ 架构模式（必选） │ 核心设计模式、数据流、分层架构
├──────────────────────────────────────┤
│ 配置说明（必选） │ vite.config、tsconfig、eslint、环境变量
├──────────────────────────────────────┤
│ 常用命令（必选） │ dev/build/lint/test 等脚本说明
├──────────────────────────────────────┤
│ 关键约定（可选） │ 命名规范、目录约定、编码规范
├──────────────────────────────────────┤
│ API / SDK 使用（可选） │ 库/框架级别项目的对外 API 说明
└──────────────────────────────────────┘
各章节编写规范
1. 项目概述
简洁说明项目是做什么的，包含：
- 项目名称（来自
package.json 的 name）
- 一句话描述（来自
package.json 的 description，有则用，没有则从代码推断）
- 核心功能列表（2-4 条要点）
- 作者/仓库信息（如有）
# 项目名称
> 一句话描述
## 核心功能
- 功能点 1
- 功能点 2
2. 技术栈
从 package.json 中提取并分类：
## 技术栈
| 类别 | 技术 | 版本 |
|------|------|------|
| 运行时 | React | ^18.3.1 |
| 语言 | TypeScript | ^5.5.3 |
| 构建工具 | Vite | ^5.4.1 |
| UI 组件库 | Ant Design | 4.24.1 |
| 状态管理 | Zustand | ^5.0.2 |
| 路由 | React Router | ^6 |
| 图表 | ECharts | ^5.6.0 |
| 代码编辑器 | Monaco Editor | ^0.52.2 |
| 国际化 | i18next | ^24.2.2 |
| ... | ... | ... |
分类方式：
- 运行时：React、React DOM
- 语言：TypeScript
- 构建工具：Vite、相关插件
- UI 组件库：Ant Design 等
- 状态管理：Zustand、Redux 等
- 路由：React Router 等
- 样式方案：Less、Sass、CSS Modules 等
- 图表/可视化：ECharts 等
- 工具库：ahooks、lodash-es、dayjs 等
- 质量工具：ESLint、Prettier、Husky 等
3. 目录结构
输出 src/ 下的完整目录树，并标注各目录职责：
## 目录结构
├── src/
│ ├── main.tsx # 应用入口
│ ├── pages/ # 页面组件
│ │ ├── index.tsx # 编辑页面（主页面）
│ │ ├── preview/ # 预览页面
│ │ └── components/ # 页面级共享组件
│ ├── components/ # 全局通用组件
│ ├── engine/ # 核心引擎
│ │ ├── index.ts # Engine 类（主入口）
│ │ ├── store/ # 全局状态（Zustand）
│ │ ├── component/ # 组件模板管理
│ │ ├── componentNode/ # 组件数据实例管理
│ │ ├── instance/ # 组件运行时行为实例
│ │ ├── hooks/ # 引擎级 hooks
│ │ ├── model/ # 基础模型（事件系统等）
│ │ ├── config/ # 配置管理
│ │ ├── page/ # 页面管理
│ │ ├── favorites/ # 收藏夹管理
│ │ ├── enum/ # 枚举常量
│ │ ├── utils/ # 工具函数
│ │ └── built-in/ # 内置组件库
│ ├── export/ # 对外 SDK 入口
│ ├── packages/ # 独立功能包
│ ├── hooks/ # 通用 hooks
│ ├── utils/ # 通用工具函数
│ ├── i18n/ # 国际化
│ ├── router/ # 路由配置
│ └── static/ # 静态资源
对于每个目录，需要标注：
- 职责：该目录负责什么
- 关键文件：目录下最重要的 1-3 个文件
4. 入口文件
描述应用启动的完整链路：
## 入口文件
### 启动链路
index.html → src/main.tsx → Router → Pages
1. **`index.html`** — HTML 模板，挂载点 `#root`
2. **`src/main.tsx`** — 应用入口
- 创建 React 根节点
- 注入路由（HashRouter）
- 引入全局样式和国际化
3. **`src/router/index.tsx`** — 路由配置
- `/` → 重定向到 `/create`
- `/create` → 编辑页面（懒加载）
- `/preview` → 预览页面（懒加载）
4. **`src/pages/index.tsx`** — 编辑主页面
- 初始化 RbsEngine 实例
- 加载初始 JSON 数据
- 监听预览事件
5. 架构模式
识别并描述项目的核心设计模式，包括：
- 核心层级结构（如：引擎层 → 数据层 → 视图层）
- 数据流（单向数据流、状态管理方式）
- 关键抽象（如数据与行为分离、模板与实例分离等）
- 模块间通信方式（事件系统、全局状态、Context 等）
- Mermaid 架构图（推荐，便于可视化理解）
## 架构模式
### 分层结构
```mermaid
graph TD
A[RbsEngine SDK 层] --> B[Engine 引擎层]
B --> C[Component 模板管理]
B --> D[ComponentNode 数据管理]
B --> E[Instance 行为管理]
B --> F[Config 配置管理]
B --> G[Page 页面管理]
D --> H[Zustand Store]
A --> I[视图层]
I --> J[RenderEditor 编辑器]
I --> K[RenderPreview 预览器]
核心设计
模板-数据-行为 三层分离
| 层 | 管理对象 | 职责 |
|---|
| Component | 组件模板 | 定义组件的 UI、属性面板、事件类型 |
| ComponentNode | 数据实例 | 组件的可持久化数据（位置、大小、配置） |
| Instance | 行为实例 | 运行时行为（hover、选中、拖拽） |
### 6. 配置说明
说明项目构建和工程化配置：
```markdown
## 配置说明
### Vite 配置（vite.config.ts）
- 开发服务器端口：`11000`
- 路径别名：`@` → `src/`
- Less 全局注入：`src/global.less`
- 代码分包策略：react-vendor / echarts / antd / monaco-editor / lodash-es / ahooks
### TypeScript 配置（tsconfig.json）
- target: ES2020
- 严格模式：开启
- JSX: react-jsx
- 路径别名：`@/*` → `src/*`
### ESLint 配置（.eslintrc.js）
- 解析器：`@typescript-eslint/parser`
- 继承：plugin:react/recommended + prettier
- 引号：双引号
### 环境变量
| 变量 | 说明 |
|------|------|
| `__DEV__` | 是否开发环境 |
| `VERSION` | 当前版本号 |
| `__LIB_MODE__` | 是否库模式构建 |
| `LIB_MODE` | 构建 ESM 库模式 |
| `mode` | 打包分析模式（analyzer） |
| `deploy` | GitHub Pages 部署标识 |
7. 常用命令
从 package.json scripts 提取：
## 常用命令
| 命令 | 说明 |
|------|------|
| `pnpm dev` | 启动开发服务器 |
| `pnpm build` | 构建生产版本 |
| `pnpm build:lib` | 构建 ESM 库 |
| `pnpm lint` | 运行 ESLint 检查 |
| `pnpm preview` | 预览构建产物 |
| `pnpm commit` | 交互式提交（commitizen） |
8. 关键约定（可选）
从代码中观察到的约定：
- 文件/目录命名规范
- 组件编写规范
- Import 顺序约定
- 注释规范（JSDoc 格式等）
9. API / SDK 使用（可选）
如果是库/框架项目，说明对外 API：
## SDK 使用
### 基本用法
\`\`\`typescript
import { RbsEngine } from "react-big-screen";
const rbsEngine = new RbsEngine();
// 挂载到 DOM
rbsEngine.mount(document.getElementById("app")!);
// 导入 JSON 数据
await rbsEngine.importJSONString(jsonText);
// 导出 JSON 数据
const json = await rbsEngine.exportJSON();
// 监听事件
rbsEngine.on("startPreview", async (engine) => {
const json = await engine.getJSON();
// 处理预览逻辑
});
// 销毁
rbsEngine.destroy();
\`\`\`
执行流程
1. 快速扫描（只读）
按顺序读取以下文件获取项目基础信息：
| 顺序 | 文件 | 获取内容 |
|---|
| 1 | package.json | 项目名、描述、依赖、scripts |
| 2 | vite.config.ts / next.config.js / webpack.config.js | 构建配置、别名、端口 |
| 3 | tsconfig.json | TS 配置、路径映射 |
| 4 | src/main.tsx / src/index.tsx / src/App.tsx | 入口文件、启动逻辑 |
| 5 | src/router/ | 路由配置、页面列表 |
| 6 | .eslintrc.js / .eslintrc.json | 代码规范配置 |
2. 目录扫描
find ./src -maxdepth 3 -type d | sort
分析 src/ 下各目录的职责和关键文件。
3. 架构分析
读取核心模块的入口文件（如 engine/index.ts、store/index.ts）以理解架构模式。
4. 生成文档
按上述章节规范生成 CLAUDE.md，写入项目根目录。文档完成后报告文件位置和各章节概要。
注意事项
- 尊重已有内容：如果项目已有 CLAUDE.md，先读取，保留其中仍有效的自定义内容（如特定业务约定），只更新客观事实部分（版本号、新增目录等）
- 版本号从 package.json 提取，不要自己编造
- 不要虚构不存在的技术，只记录项目中实际使用的依赖
- 目录树展示 2-3 层即可，避免过深导致文档臃肿
- 架构图用 Mermaid，便于渲染和阅读
- 不要包含 .claude/、node_modules/、dist/、.git/ 等工具/构建目录
- 如果某可选章节不适用，就跳过，不要硬写
- 文档长度控制在 300-500 行，保持精炼
