project-structure-designer

name	project-structure-designer
description	基于已确认的技术栈方案，设计项目整体结构骨架——分层架构、代码组织、目录布局、 层间数据流与技术映射，产出项目结构设计文档。 触发场景： (1) 技术栈方案已确认，需要设计项目目录与代码组织结构； (2) 用户要求规划 monorepo 包划分、模块目录骨架或分层架构； (3) 用户提及"项目结构"、"目录规划"、"分层设计"、"project structure"、"代码组织"等关键词； (4) 作为项目设计流水线中技术栈设计后的下一环节。

项目结构设计 Skill

核心原则

• 技术栈驱动：所有结构设计必须以已确认的技术栈方案为依据，不得凭空设计。
• 分层清晰：每层职责单一，层间依赖方向明确（上层依赖下层，禁止反向）。
• 落地优先：产出的目录结构必须可直接用于项目初始化（mkdir -p 或脚手架生成）。
• 中文输出：所有输出文本使用中文，代码与专有名词除外。

输入要求

执行前，按优先级读取以下文档：

1. docs/项目名称-技术栈设计.md — 必须存在。技术栈方案是项目结构设计的唯一权威输入。若不存在，上报 ERROR，说明缺失上游产物。
2. .tmp/requirements-context.md — 若存在，补充需求上下文（部署环境、规模约束等）。
3. .tmp/architecture-decisions.md — 若存在，补充架构关节点选型细节。

执行流程

步骤 1：读取技术栈方案并提取结构因子

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 多人按领域分工）

2. 若 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：设计层间数据流

描述关键业务场景的数据在各层之间的流转路径：

1. 选取 2-3 个代表性业务场景（如"用户请求 → 响应"、"异步事件处理"、"定时任务"）
2. 用文字描述数据流经的各层及其转换过程
3. 标注每层的输入/输出数据形态（DTO、Entity、VO、Domain Event 等）

步骤 6：编写输出文档

按 references/output-template.md 的精确结构输出到 docs/项目名称-项目结构.md。

输出文档结构：

1. 技术栈回顾 — 摘要式回顾技术栈关键选型（为结构设计提供上下文）
2. 选定的结构模式 — 记录步骤 2 选定的各维度模式及选择理由
3. 分层架构 — 每层的职责、内容、技术组件、依赖方向
4. 目录骨架 — 带注释的完整目录树（基于选定模式的具体目录布局）
5. 层间数据流 — 2-3 个代表性场景的数据流转描述
6. 包/模块组织约定 — 命名规范、文件组织规则、import/export 约定
7. 扩展预留 — 为未来可能引入的组件预留的目录位置

交付前自检

• 结构模式选择有明确依据（项目规模、团队规模、技术栈匹配）
• 分层架构与技术栈方案中的每一项技术都有明确归属
• 层间依赖方向均为单向（上层→下层），无循环依赖
• 目录骨架可直接用于项目初始化（每个目录都有明确的职责说明）
• 命名约定与技术栈社区最佳实践一致
• 至少描述了 2 个代表性业务场景的数据流
• 若为 monorepo，各 package 的边界已明确

自检通过后，发起 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