# Project Structure Init

> 根据《软件工程目录规范》自动创建仓库级和工程级（C++）的完整目录结构及文档骨架。自动识别当前目录所属级别，仓库级则逐级向下完成全部初始化。当用户说"初始化项目结构"、"创建仓库目录"、"搭建工程结构"、"按规范创建目录"、"初始化docs"、"创建C++工程"时触发。增量创建，已存在的文件和目录不会覆盖。

- Skill: `herxinsasa/project-structure-init` (Agent Skill, multi-file: 28 files)
- Install (CLI): `npx skillmds@latest add herxinsasa/project-structure-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/herxinsasa/project-structure-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: herxinsasa (https://skillmd.com/u/herxinsasa)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/herxinsasa/project-structure-init

---


# 项目结构初始化 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 模板内容**：

```markdown
# [目录名] — AI 上下文入口

## 项目定位

<!-- 一句话描述该工程的用途 -->

## 技术栈

| 工程 | 语言 | 框架 |
|------|------|------|
|      |      |      |

## 子工程清单

| 子工程 | 类型 | 职责 |
|--------|------|------|
|       | C++ |      |

## 文档地图

- `docs/` — 仓库级文档
- `projects/<name>/docs/` — 各子工程文档
```

**README.md 模板内容**：

```markdown
# [目录名]

## 简介

<!-- 工程用途和定位 -->

## 技术栈

<!-- 主要技术栈 -->

## 快速开始

<!-- 构建和运行方式 -->
```

**创建规则**：每个目录/文件创建前先检查是否存在，已存在则跳过并记录。

#### 2.2 docs/ 文档目录

读取 `references/仓库级/` 下的目录树（用 `find` 或 `ls -R`），在 `<repo_root>/docs/` 下创建完全相同的结构。

每个文件的创建逻辑：
1. 拼出目标路径：`<repo_root>/docs/<相对路径>`
2. 检查是否存在 → 存在则跳过
3. 不存在 → 读取 `references/仓库级/<相对路径>` 的模板内容 → 写入目标文件
4. 空目录（如 `原型设计/`）创建 `.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 模板**：

```markdown
# [工程名] — 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` 空文件 |

## 注意事项

1. 模板文件在 `references/仓库级/` 和 `references/工程级/` 下，结构与目标路径一一对应
2. 创建文件时，`Read` 对应 reference 文件，将其全部内容写入目标文件
3. `references/软件工程目录规范_v1.0.md` 是规范全文，创建前先读一遍作为总览
4. 仓库级识别到后自动级联所有 C++ 子工程，不遗漏
5. 空目录放 `.gitkeep` 以纳入版本控制
6. 已存在的内容不作任何修改