Project Structure Init

项目结构初始化 Skill

概述

根据《软件工程目录规范 v1.0》，自动识别目录层级，为 C++ 项目创建标准化的仓库级和工程级目录结构及文档骨架。

核心原则

• 自动识别级别：扫描目标目录特征，自动判断是仓库级还是工程级
• 逐级向下：仓库级完成后，自动扫描 projects/ 下的 C++ 子工程并逐个初始化
• 增量创建：目录或文件已存在则跳过，不修改、不覆盖
• 缺啥补啥：对照模板逐项检查，只创建缺失项
• 文档内容即模板：创建文件时，将 reference 中对应的模板内容写入新文件

工作流程

Step 1: 确定目标路径并自动识别级别

取用户提供的路径，无则用当前工作目录。

1.1 级别识别规则

按优先级判断：

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/ 下创建完全相同的结构。

每个文件的创建逻辑：

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 模板：

# [工程名] — 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>
...

增量创建规则

注意事项

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