# claude-codegen

**Repository Path**: jamywwu/claude-codegen

## Basic Information

- **Project Name**: claude-codegen
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-11
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# claude-codegen

> Claude Code 代码生成工作流标准化插件

一键注入规则、技能、Hook 脚本到任意 Vue 3 + Element Plus 前端项目，让 Claude Code 具备标准化的代码生成能力。

**仓库地址**：https://gitee.com/jamywwu/claude-codegen

## 快速开始

```bash
# 方式一：全局安装（推荐）
npm install -g git+https://gitee.com/jamywwu/claude-codegen.git
claude-codegen init --all

# 方式二：npx 直接使用
npx git+https://gitee.com/jamywwu/claude-codegen.git init --all

# 方式三：已 clone 到本地
cd /path/to/claude-codegen && npm link
claude-codegen init --all
```

初始化后，Claude Code 会自动加载所有规则和技能。

## 工作流程

```
① 接口文档 (JSON)     ← 字段名唯一来源（Query/Vo/Dto）
② PRD 文档 (Word/PDF) ← 业务规则、数据字典、状态流转
③ 设计稿 (Axure/截图)  ← 页面布局、字段排列、按钮样式
        │
        ▼  doc-generator 技能（三源合并）
需求文档 (.md)
   ├── 原型图嵌入
   ├── 接口字段映射对照表
   └── 代码级字段配置（prop 使用接口字段名）
        │
        ▼  page-builder 技能
代码文件
   ├── src/views/{模块}/{页面}/index.vue
   ├── src/views/{模块}/{页面}/detail.vue
   ├── src/api/{模块}/{页面}.js
   └── 路由注册
        │
        ▼  code-reviewer 技能
代码审查（Vue 3 最佳实践 + 架构守卫）
```

## 安装了什么

### 规则文件（`.claude/rules/`）
| 文件 | 作用 |
|------|------|
| `vue-code-style.md` | Vue 组件规范（script setup、ref 优先、弹窗模式、Promise 链提交） |
| `api-style.md` | API 文件规范（CRUD 方法名、POST 模板、JSDoc 注释） |
| `layout-style.md` | 布局样式规范（列表页/详情页容器、全局 CSS 类） |

### 技能文件（`.claude/skills/`）
| 技能 | 作用 | 触发文件 |
|------|------|---------|
| `page-builder` | CRUD 页面生成器（接口文档字段严格映射） | 手动触发 |
| `doc-generator` | 需求文档生成器（**接口文档 + PRD + 设计稿** 三源合并） | 手动触发 |
| `code-reviewer` | 代码审查（Vue 3 最佳实践 + 架构守卫） | `src/**/*.{vue,js,ts}` |
| `env-manager` | 环境变量管理（多环境配置） | `.env*`、`vite.config.*` |

### Hook 脚本（`scripts/`）
| 脚本 | 触发时机 | 作用 |
|------|---------|------|
| `preflight.sh` | SessionStart | 环境检查（node_modules、.env、vite） |
| `arch_lint.sh` | SessionStart | 架构守卫（禁止直接 axios、API 必须在 src/api/ 下） |
| `session-log.sh` | Stop | 自动记录会话日志到 docs/dev-logs/ |

### .gitignore 自动管理
init 自动将生成文件加入 `.gitignore`（标记块隔离），不影响项目提交：
```gitignore
# >>> claude-codegen managed >>>
.claude-codegen.json
.claude/rules/
.claude/skills/
scripts/preflight.sh
...
# <<< claude-codegen managed <<<
```

### 配置合并
自动合并 hooks 和 permissions 到 `.claude/settings.local.json`，追加不重复，不覆盖已有配置。

### CLAUDE.md 自动注入
init 自动在 `CLAUDE.md` 中注入代码生成工作流提示，Claude Code 启动时即可了解可用技能和使用方式。

### 启动就绪提示
Claude Code 启动时，preflight.sh 自动检测并提示：
- ✅ 已安装：`🚀 claude-codegen 已就绪 (3 规则 / 4 技能)`
- 💡 未安装：`未检测到 claude-codegen，运行 claude-codegen init --all 启用`

### 覆盖前自动备份
使用 `--force` 覆盖已有文件时，自动创建 `.bak` 备份：
```
.claude/rules/vue-code-style.md      ← 新文件
.claude/rules/vue-code-style.md.bak  ← 覆盖前的备份
```

## CLI 命令

### init — 初始化
```bash
# 完整初始化（非交互，全部安装）
claude-codegen init --all

# 交互式选择安装范围
claude-codegen init

# 按需安装
claude-codegen init --rules-only      # 只装规则
claude-codegen init --skills-only     # 只装技能
claude-codegen init --hooks-only      # 只装 Hook 脚本
claude-codegen init --docs-only       # 只装文档模板

# 预览模式（只显示将要安装的文件，不实际写入）
claude-codegen init --all --dry-run

# 强制覆盖已有文件（自动备份 .bak）
claude-codegen init --all --force

# 预览强制覆盖效果
claude-codegen init --all --dry-run --force
```

### status — 查看状态
```bash
# 查看管理状态（同步/已修改/缺失/已脱管）
claude-codegen status
```

### update — 更新
```bash
# 更新到最新版本（三路比较，不覆盖项目自定义）
claude-codegen update

# 预览更新效果（不修改文件）
claude-codegen update --dry-run

# 强制更新（覆盖冲突文件，自动备份 .bak）
claude-codegen update --force
```

### eject — 脱管
```bash
# 脱管某个文件（保留文件但不再自动更新）
claude-codegen eject .claude/rules/vue-code-style.md
```

## doc-generator 三源输入详解

需求文档生成时的三个信息来源及职责：

| 来源 | 提供什么 | 必要性 |
|------|---------|--------|
| **接口文档 (JSON)** | 字段名（prop）、字段类型、接口地址 | 必须 ✅ |
| **PRD 文档** | 业务规则、数据字典、状态流转、权限 | 必须 ✅ |
| **设计稿** | 页面布局、字段排列、按钮样式 | 推荐 |

### 字段映射对照表（自动生成）

每个需求文档都包含映射表，确保代码中的 prop 和接口文档一致：

| 需求中文名 | 接口字段名 | Query | Vo | Dto | 用途 |
|-----------|-----------|:-----:|:--:|:---:|------|
| 问题编号 | problemNo | ✅ | ✅ | | 查询+列表 |
| 问题状态 | problemStatus | ✅ | ✅ | | 查询+列表(tag) |

### 支持的设计稿格式

| 格式 | 来源 | 处理方式 |
|------|------|---------|
| Axure HTML 导出 | `axure/` 目录 | 解析 HTML 提取元素 |
| PNG/JPG 截图 | `docs/requirements/image-*.png` | 嵌入文档引用 |
| 在线链接 | Figma/蓝湖 URL | web_reader 读取 |

### 支持的接口文档格式

| 格式 | Schema 位置 | 请求体 |
|------|-----------|--------|
| OpenAPI 3.0 | `components/schemas` | `requestBody` |
| Swagger 2.0 | `definitions` | `parameters[in:body]` |

## 项目自定义

### 脱管单个文件
```bash
claude-codegen eject .claude/rules/vue-code-style.md
```
文件保留在磁盘，不再被 `update` 管理，可自由编辑。

### 添加项目级规则
在 `.claude/rules/` 下新建 `.md` 文件（如 `project-overrides.md`），与插件管理的文件共存。

### 添加自定义技能
在 `.claude/skills/` 下新建目录和 `skill.md`，与插件管理的技能共存。

## 更新策略

`claude-codegen update` 使用三路比较：

| 模板变了？ | 你改了？ | 操作 |
|-----------|---------|------|
| 没变 | 没变 | 跳过 |
| 没变 | 改了 | 保留你的 |
| 变了 | 没改 | 自动更新 |
| 变了 | 改了 | 提示冲突（--force 强制，自动备份） |

## 安全机制

| 机制 | 说明 |
|------|------|
| `.gitignore` 标记块 | 生成文件不污染项目提交 |
| 三路哈希比较 | 更新时不会意外覆盖你的修改 |
| `.bak` 自动备份 | `--force` 覆盖前自动备份原文件 |
| `--dry-run` 预览 | 所有写操作都支持预览模式 |
| 冲突提示 | 检测到冲突时跳过并提示，不会静默覆盖 |

## 文件结构

init 后项目中新增/修改的文件：

```
.claude/
  rules/
    vue-code-style.md            # Vue 组件规则
    api-style.md                 # API 文件规则
    layout-style.md              # 布局样式规则
  skills/
    page-builder/skill.md        # CRUD 页面生成器
    doc-generator/skill.md       # 需求文档生成器
    code-reviewer/skill.md       # 代码审查
    env-manager/skill.md         # 环境管理
  settings.local.json            # ← 合并 hooks + permissions
scripts/
  preflight.sh                   # 环境检查 Hook
  arch_lint.sh                   # 架构守卫 Hook
  session-log.sh                 # 会话日志 Hook
docs/
  quick-start.md                 # 快速开始指南
  plans/_template.md             # 计划模板
.claude-codegen.json             # 管理清单（哈希追踪）
.gitignore                       # ← 追加管理文件忽略规则
```

## 技术要求

- Node.js >= 14
- Vue 3 + Element Plus 项目（自动检测）
- 零依赖，不安装任何 npm 包

## License

MIT