| name | project-structure-init |
| description | 根据《软件工程目录规范》自动创建仓库级和工程级（C++）的完整目录结构及文档骨架。自动识别当前目录所属级别，仓库级则逐级向下完成全部初始化。当用户说"初始化项目结构"、"创建仓库目录"、"搭建工程结构"、"按规范创建目录"、"初始化docs"、"创建C++工程"时触发。增量创建，已存在的文件和目录不会覆盖。 |
项目结构初始化 Skill
概述
根据《软件工程目录规范 v1.0》，自动识别目录层级，为 C++ 项目创建标准化的仓库级和工程级目录结构及文档骨架。
核心原则
- 自动识别级别：扫描目标目录特征，自动判断是仓库级还是工程级
- 逐级向下：仓库级完成后，自动扫描
projects/ 下的 C++ 子工程并逐个初始化
- 增量创建：目录或文件已存在则跳过，不修改、不覆盖
- 缺啥补啥：对照模板逐项检查，只创建缺失项
- 文档内容即模板：创建文件时，将 reference 中对应的模板内容写入新文件
工作流程
Step 1: 确定目标路径并自动识别级别
取用户提供的路径，无则用当前工作目录。
1.1 级别识别规则
按优先级判断：
| 条件 | 判定 | 后续动作 |
|---|
目录下存在 projects/ 子目录 | 仓库级 | 执行 Step 2 → Step 3（逐个初始化子工程） |
路径包含 projects/<name>/ 或存在 xmake.lua | 工程级（C++） | 执行 Step 3 |
存在 src/ + include/ 目录 | 工程级（C++） | 执行 Step 3 |
| 以上都不满足 | 不确定 | 询问用户：要初始化为仓库级还是工程级 |
1.2 自动级联原则
仓库级初始化完成后，自动扫描 projects/ 下的所有子目录，对每个 C++ 子工程（存在 xmake.lua 或 src/ 目录）执行工程级初始化。已有的不重复创建。
1.3 用户可指定子工程
如果目录是工程级，用户可选指定工程名；未指定则取当前目录名。
Step 2: 仓库级初始化
以目标路径为 <repo_root>，按以下顺序创建：
2.1 根目录固定结构
逐个检查并创建：
<repo_root>/
├── .gitignore ──── 标准 C++ 忽略规则（*.o *.obj *.exe *.dll *.so build/ bin/ lib/ .vs/ .vscode/ node_modules/ *.log *.pid .env）
├── README.md ──── 含标题和简介/技术栈/快速开始占位段落
├── CLAUDE.md ──── 含项目定位/技术栈/子工程清单/文档地图占位段落
├── docs/ ──── 目录，按 2.2 创建
├── scripts/ci/ ──── 目录 + .gitkeep
├── scripts/sql/ ──── 目录 + .gitkeep
├── tools/ ──── 目录 + .gitkeep
└── projects/ ──── 目录 + .gitkeep
CLAUDE.md 模板内容：
# [目录名] — AI 上下文入口
## 项目定位
<!-- 一句话描述该工程的用途 -->
## 技术栈
| 工程 | 语言 | 框架 |
|------|------|------|
| | | |
## 子工程清单
| 子工程 | 类型 | 职责 |
|--------|------|------|
| | C++ | |
## 文档地图
- `docs/` — 仓库级文档
- `projects/<name>/docs/` — 各子工程文档
README.md 模板内容：
# [目录名]
## 简介
<!-- 工程用途和定位 -->
## 技术栈
<!-- 主要技术栈 -->
## 快速开始
<!-- 构建和运行方式 -->
创建规则：每个目录/文件创建前先检查是否存在，已存在则跳过并记录。
2.2 docs/ 文档目录
读取 references/仓库级/ 下的目录树（用 find 或 ls -R），在 <repo_root>/docs/ 下创建完全相同的结构。
每个文件的创建逻辑：
- 拼出目标路径：
<repo_root>/docs/<相对路径>
- 检查是否存在 → 存在则跳过
- 不存在 → 读取
references/仓库级/<相对路径> 的模板内容 → 写入目标文件
- 空目录（如
原型设计/）创建 .gitkeep
预期创建的完整结构（与 references/仓库级/ 对应）：
docs/
├── 01-总览/
│ ├── 系统架构总览.md
│ └── 目录结构.md
├── 02-需求/
│ ├── 需求规格说明书.md
│ └── 需求影响分析矩阵.md
├── 03-概设/
│ ├── 客户端概要设计.md
│ └── 服务端概要设计.md
├── 04-协议/
│ ├── 通信协议.md
│ ├── 数据格式规范.md
│ └── 全局错误码.md
├── 05-UI/
│ ├── UI设计规范.md
│ └── 原型设计/
├── 06-测试/
│ ├── 测试方案.md
│ └── 测试报告.md
└── 07-工程说明/
├── client.md
├── server.md
└── robot.md
Step 3: 工程级初始化（C++）
对 projects/<工程名>/ 路径执行（仓库级级联时逐个执行此步骤）。
3.1 C++ 子工程固定目录结构
projects/<工程名>/
├── .gitignore ──── C++ 子工程忽略规则
├── README.md ──── 子工程说明模板
├── CLAUDE.md ──── AI 上下文入口模板
├── xmake.lua ──── 构建骨架
├── src/ ──── 目录
│ └── internal/ ──── 目录 + .gitkeep
├── include/ ──── 目录 + .gitkeep
├── config/ ──── 目录 + .gitkeep
├── scripts/ ──── 目录 + .gitkeep
├── test/ ──── 目录 + .gitkeep
└── docs/ ──── 目录，按 3.2 创建
CLAUDE.md 模板：
# [工程名] — AI 上下文入口
## 本工程架构
<!-- 分层描述或一句话概括 -->
## 关键约定
- 编码规范参见 `docs/02-规范/编码规范.md`
- 模块依赖参见 `docs/03-模块依赖/模块索引.md`
## 构建
```bash
xmake build
xmake run
文档地图
docs/01-总览/ — 架构总览与目录结构docs/03-模块依赖/ — 模块依赖关系docs/04-设计/ — 功能设计文档
**xmake.lua 模板**：
```lua
add_rules("mode.debug", "mode.release")
target("[工程名]")
set_kind("binary")
add_files("src/*.cpp")
add_includedirs("include")
3.2 docs/ 文档目录
与仓库级 docs 创建方式相同，对照 references/工程级/ 创建：
docs/
├── 01-总览/
│ ├── 架构总览.md
│ └── 目录结构.md
├── 02-规范/
│ ├── 编码规范.md
│ ├── 错误码.md
│ └── 测试规范.md
├── 03-模块依赖/
│ ├── 模块索引.md
│ └── 示例模块/
│ └── README.md
└── 04-设计/
├── 架构设计.md
└── 应用设计/
├── 设计文档模板.md
└── 设计说明.md
Step 4: 输出摘要
## 初始化完成
**目标**: <repo_root>
**识别级别**: 仓库级 → 已级联 <N> 个 C++ 子工程
### 仓库级
已创建目录: <N> 个
已创建文件: <M> 个
已跳过 (已存在): <K> 项
### 工程级: <工程名1>
已创建目录: <N> 个
已创建文件: <M> 个
已跳过: <K> 项
### 工程级: <工程名2>
...
增量创建规则
| 操作 | 已存在时 | 不存在时 |
|---|
| 创建目录 | 跳过，记录 [跳过] | mkdir -p |
| 创建文件 | 完全跳过，不读不写 | 读取 reference 模板 → 写入目标 |
| .gitkeep | 同上 | touch 空文件 |
注意事项
- 模板文件在
references/仓库级/ 和 references/工程级/ 下，结构与目标路径一一对应
- 创建文件时，
Read 对应 reference 文件，将其全部内容写入目标文件
references/软件工程目录规范_v1.0.md 是规范全文，创建前先读一遍作为总览- 仓库级识别到后自动级联所有 C++ 子工程，不遗漏
- 空目录放
.gitkeep 以纳入版本控制
- 已存在的内容不作任何修改
