feature-arch

基于功能的架构最佳实践

全面的架构指南，介绍如何按功能组织 React 应用，以支持独立团队进行可扩展的开发。包含 8 个类别共 43 条规则，按影响从关键（目录结构、导入）到渐进式（命名约定）排序。在实际项目中调用此技能时，它会生成一份针对该项目的蓝图，并以这些规则为每项决策提供依据。

主要产出：目标架构蓝图

Agent 在实际项目中调用此技能时，交付物是一份 Markdown 文件，保存至 docs/architecture/FEATURE-ARCH-TARGET.md（或仓库现有的文档位置）。蓝图包含：

1. 项目背景 — 框架、状态库、路由模型、当前结构。
2. 已识别的功能 — 与用户确认，并从路由、文档、openspec 和代码集群中提取。
3. 目标目录树 — 使用实际路径，而非伪目录树。
4. 各功能的公共 API — 每个 index.ts 的确切具名导出。
5. 导入边界矩阵 — 功能关系的 N×N 表格（allowed / forbidden / via app / via events）。
6. 状态与数据所有权 — 各功能对应的服务端状态和客户端状态所有者。
7. 跨功能通信策略 — 组合、事件或共享切片，并说明理由。
8. 编号迁移计划 — 文件级移动/创建/删除步骤，并估算 S/M/L 工作量。
9. 人工合规检查清单 — 用于代码审查和“完成定义”。
10. 待解决问题 — 迁移前需要人工决策的事项。

每个部分都会引用下方管理相关决策的具体规则，确保蓝图是此技能的投影，而非另一个并行的权威来源。

Agent 如何生成蓝图

遵循 references/_blueprint-process.md 中的流程。概要：

1. 收集背景信息（package.json、src/ 目录树、README、CLAUDE.md、openspec/）。
2. 从路由、文档和代码集群中识别候选功能。
3. 通过 AskUserQuestion 与用户确认功能列表。
4. 记录明确决策（分层模型、通信机制、状态/路由所有者）。
5. 填写 assets/templates/feature-arch-target.md.template — 将每个 {{placeholder}} 替换为项目中的实际值。
6. 移交：打印路径、概述功能数/步骤数、列出最重要的 3 项风险，并建议下一步行动。同一轮中不要开始执行迁移步骤。

对于非常小的项目（源文件少于约 10 个），改为生成一页的初始结构，并注明应在第 2–3 个功能出现后再制定完整蓝图。

适用场景

在以下情况下参考这些指南：

• 项目要求制定基于功能的目标架构（生成蓝图）。
• 创建新功能或模块。
• 组织项目目录结构。
• 设置导入规则和边界。
• 实施数据获取模式。
• 组合来自多个功能的组件。
• 审查代码中的架构违规。

按优先级划分的规则类别

优先级	类别	影响	前缀
1	目录结构	关键	struct-
2	导入与依赖	关键	import-
3	模块边界	高	bound-
4	数据获取	高	fquery-
5	组件组织	中高	fcomp-
6	状态管理	中	fstate-
7	测试策略	中	test-
8	命名约定	低	name-

快速参考

1. 目录结构（关键）

• struct-feature-folders - 按功能组织，而非按技术类型组织
• struct-feature-self-contained - 使功能保持自包含
• struct-shared-layer - 共享层仅用于真正通用的代码
• struct-flat-hierarchy - 保持目录层级扁平
• struct-optional-segments - 仅包含必要的部分
• struct-app-layer - 将应用层与功能分开
• struct-domain-folders - 在大型项目中将功能归入不同领域

2. 导入与依赖（关键）

• import-unidirectional-flow - 强制采用单向导入流程
• import-no-cross-feature - 禁止跨功能导入
• import-public-api - 仅通过公共 API 导出
• import-avoid-barrel-files - 避免通过深层 barrel 文件重新导出
• import-path-aliases - 使用一致的路径别名
• import-type-only - 类型仅使用类型导入

3. 模块边界（高）

• bound-feature-isolation - 强制功能隔离
• bound-interface-contracts - 定义明确的接口契约
• bound-feature-scoped-routing - 将路由范围限定在功能相关内容内
• bound-minimize-shared-state - 尽量减少功能间的共享状态
• bound-event-based-communication - 使用事件进行跨功能通信
• bound-feature-size - 确保功能规模适当

4. 数据获取（高）

• fquery-single-responsibility - 使查询函数各司其职
• fquery-colocate-with-feature - 将数据获取代码与功能放在一起
• fquery-parallel-fetching - 并行获取彼此独立的数据
• fquery-avoid-n-plus-one - 避免 N+1 查询模式
• fquery-feature-scoped-keys - 使用功能范围限定的查询键
• fquery-server-component-fetching - 在服务端组件层获取数据

5. 组件组织（中高）

• fcomp-single-responsibility - 遵循组件单一职责原则
• fcomp-composition-over-props - 优先使用组合，而非逐层传递 props
• fcomp-container-presentational - 分离容器与展示职责
• fcomp-props-as-data-boundary - 使用 props 作为功能边界
• fcomp-colocate-styles - 将样式与组件放在一起
• fcomp-error-boundaries - 使用功能级错误边界

6. 状态管理（中）

• fstate-feature-scoped-stores - 将状态存储限定在功能范围内
• fstate-server-state-separation - 将服务端状态与客户端状态分开
• fstate-lift-minimally - 仅在必要时提升状态
• fstate-context-sparingly - 谨慎使用 context 管理功能状态
• fstate-reset-on-unmount - 在卸载时重置功能状态

7. 测试策略（中）

• test-colocate-with-feature - 将测试与功能放在一起
• test-feature-isolation - 独立测试各项功能
• test-shared-utilities - 创建功能专用的测试工具
• test-integration-at-app-layer - 在应用层编写集成测试

8. 命名约定（低）

• name-feature-naming - 使用领域驱动的功能名称
• name-file-conventions - 使用一致的文件命名约定
• name-descriptive-exports - 使用描述性导出名称

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• Blueprint 流程 - 如何推导出适用于特定项目的目标架构
• Blueprint 模板 - Agent 用于生成最终状态文档的模板
• 章节定义 - 类别结构和影响级别
• 规则模板 - 用于添加新规则的模板
• 各项规则：references/{prefix}-{slug}.md

相关技能

• 功能规划请参阅 feature-spec 技能
• 数据获取请参阅 tanstack-query 技能
• React 组件模式请参阅 react-19 技能

完整汇编文档

如需查看包含所有展开规则的完整指南：AGENTS.md