| name | project-structure-designer |
| description | 基于已确认的技术栈方案，设计项目整体结构骨架——分层架构、代码组织、目录布局、 层间数据流与技术映射，产出项目结构设计文档。 触发场景： (1) 技术栈方案已确认，需要设计项目目录与代码组织结构； (2) 用户要求规划 monorepo 包划分、模块目录骨架或分层架构； (3) 用户提及"项目结构"、"目录规划"、"分层设计"、"project structure"、"代码组织"等关键词； (4) 作为项目设计流水线中技术栈设计后的下一环节。
|
项目结构设计 Skill
核心原则
- 技术栈驱动：所有结构设计必须以已确认的技术栈方案为依据，不得凭空设计。
- 分层清晰：每层职责单一，层间依赖方向明确（上层依赖下层，禁止反向）。
- 落地优先：产出的目录结构必须可直接用于项目初始化（
mkdir -p 或脚手架生成）。
- 中文输出：所有输出文本使用中文，代码与专有名词除外。
输入要求
执行前，按优先级读取以下文档：
docs/项目名称-技术栈设计.md — 必须存在。技术栈方案是项目结构设计的唯一权威输入。若不存在，上报 ERROR，说明缺失上游产物。.tmp/requirements-context.md — 若存在，补充需求上下文（部署环境、规模约束等）。.tmp/architecture-decisions.md — 若存在，补充架构关节点选型细节。
执行流程
步骤 1：读取技术栈方案并提取结构因子
-
读取 docs/项目名称-技术栈设计.md，提取以下结构因子：
- 前端框架 → 决定前端目录结构范式（如 Next.js App Router vs Vue SFC vs SvelteKit）
- 后端语言/框架 → 决定后端包组织范式（如 Go layout、Java package、Python package）
- 架构模式 → 决定顶层分层（如 MVC、Clean Architecture、Hexagonal、分层单体、微服务）
- 数据存储 → 决定数据访问层组织方式
- 部署方式 → 决定是否需要 Dockerfile、K8s 配置、CI/CD 目录
- 实时通信 → 决定是否需要独立的 WebSocket/事件层
- 认证方案 → 决定安全层/中间件的放置位置
- 项目规模 → 决定目录组织粒度（小型/MVP vs 中大型/长期维护）
- 团队规模 → 决定模块拆分策略（单人多角色 vs 多人按领域分工）
-
若 docs/项目名称-技术栈设计.md 不存在，上报 ERROR，停止执行。
步骤 2：选择具体结构模式
读取 references/patterns-by-stack.md，根据步骤 1 提取的结构因子，为每个技术栈维度匹配最合适的结构模式：
前端模式选择：
| 条件 | 推荐模式 | 参考章节 |
|---|
| React + 中大型项目（>3 人或长期维护） | Feature-Based | §1 模式 A |
| React + 小型/MVP 项目 | Layer-Based | §1 模式 B |
| Vue 3 + 中大型项目 | 企业 Feature-Based 扩展 | §2 |
| Vue 3 + 小型项目 | 官方推荐（Vite/CLI） | §2 |
后端模式选择：
| 条件 | 推荐模式 | 参考章节 |
|---|
| FastAPI + 标准 Web 项目 | 三层架构（api/services/repositories） | §3 模式 A |
| FastAPI + 复杂领域/多数据源 | Clean Architecture | §3 模式 B |
| NestJS | 官方模块驱动 | §4 |
| Express/Koa 轻量 | routes/controllers/services 分层 | §4 |
| Go/Gin | 标准分层（cmd/internal/pkg） | §5 |
Monorepo 模式选择：
| 条件 | 推荐模式 | 参考章节 |
|---|
| 前后端分离 + 共享库 | 按应用边界分层 | §6 模式 A |
| 后端领域边界清晰 + 按领域分工 | 领域驱动 Monorepo | §6 模式 B |
Python 包布局：
| 条件 | 推荐模式 | 参考章节 |
|---|
| 需 pip install 或发布到 PyPI | src-layout | §7 |
| 仅作为应用运行 | flat-layout | §7 |
选择完成后，记录选定的模式组合（如"React Feature-Based + FastAPI 三层 + 应用边界 Monorepo"），作为步骤 3-4 的设计依据。
步骤 3：基于选定模式细化分层架构
基于步骤 2 选定的结构模式，细化项目的分层架构。按需从以下维度选择适用的层：
- 表示层：UI 组件、页面、路由、视图模板
- 应用层：用例编排、业务流程、DTO 组装、权限校验
- 领域层：业务实体、值对象、领域服务、仓储接口
- 基础设施层：数据库实现、外部 API 适配器、消息队列、缓存、文件存储
- 公共层：共享类型、常量、工具函数、通用中间件
分层约束：
- 依赖方向：表示层 → 应用层 → 领域层 → 基础设施层（基础设施层实现领域层定义的接口）
- 每层列出：职责概述、包含的典型内容、对应的技术栈组件
- 标注层间通信方式（接口/事件/共享类型）
步骤 4：设计顶层目录骨架
将步骤 2 选定的结构模式映射为具体的目录树。直接引用 references/patterns-by-stack.md 中对应模式的目录结构作为起点，根据项目实际情况调整。
产出格式为带注释的目录树。以下为 Clean Architecture 通用示例（实际产出应优先使用步骤 2 选定的模式）：
# 示例：Clean Architecture 通用分层（仅作参考，优先使用选定模式）
project-root/
├── src/
│ ├── presentation/ # 表示层 — Next.js pages、React components
│ ├── application/ # 应用层 — use cases、DTOs、orchestrators
│ ├── domain/ # 领域层 — entities、value objects、repository interfaces
│ ├── infrastructure/ # 基础设施层 — DB adapters、external API clients、cache
│ └── shared/ # 公共层 — shared types、utils、constants
├── tests/
├── docs/
├── scripts/
├── .claude/
└── [框架特定文件]
设计规则：
- 目录命名统一使用 kebab-case（前端）或 snake_case（Python/后端），遵循技术栈社区惯例
- 每个目录必须标注其对应的架构层
- 标注各目录的依赖方向（谁可以引用谁）
- 若为 monorepo，明确各 package 的边界与共享策略
步骤 5：设计层间数据流
描述关键业务场景的数据在各层之间的流转路径：
- 选取 2-3 个代表性业务场景（如"用户请求 → 响应"、"异步事件处理"、"定时任务"）
- 用文字描述数据流经的各层及其转换过程
- 标注每层的输入/输出数据形态（DTO、Entity、VO、Domain Event 等）
步骤 6：编写输出文档
按 references/output-template.md 的精确结构输出到 docs/项目名称-项目结构.md。
输出文档结构：
- 技术栈回顾 — 摘要式回顾技术栈关键选型（为结构设计提供上下文）
- 选定的结构模式 — 记录步骤 2 选定的各维度模式及选择理由
- 分层架构 — 每层的职责、内容、技术组件、依赖方向
- 目录骨架 — 带注释的完整目录树（基于选定模式的具体目录布局）
- 层间数据流 — 2-3 个代表性场景的数据流转描述
- 包/模块组织约定 — 命名规范、文件组织规则、import/export 约定
- 扩展预留 — 为未来可能引入的组件预留的目录位置
交付前自检
自检通过后，发起 AskUserQuestion 将结构设计方案呈现给用户终审，选项为："通过"（确认结构方案）、"调整结构"（修正分层或目录布局）、"放弃"（终止工作流）。
约束与禁忌
- 禁止脱离技术栈设计：所有结构决策必须能在技术栈方案中找到依据。
- 禁止层间反向依赖：基础设施层不得依赖表示层，领域层不得依赖应用层。
- 禁止过度设计：不为未规划的功能预留复杂的目录层级或抽象层。
- 禁止命名不一致：同类目录/文件必须使用统一的命名风格（全 kebab-case 或全 snake_case，不可混用）。
参考文件索引
| 文件 | 归属 | 用途 | 加载时机 |
|---|
references/output-template.md | Skill 独有 | 项目结构文档的精确结构与各节填写规范 | 步骤 6 |
references/patterns-by-stack.md | Skill 独有 | 按技术栈的常见项目结构模式参考（React/Vue/FastAPI/NestJS/Go/Monorepo/Python） | 步骤 2 |
.claude/workflows/project-design-pipeline/references/directory-convention.md | 工作流共享 | 全局目录结构约定（产物路径、命名规则） | 步骤 1 启动时 |
docs/项目名称-技术栈设计.md | 上游产物 | 技术栈选型记录（主数据源） | 步骤 1 |
