domain-organization

领域组织

按 所有者 → 角色 → 模块 组织源代码。路径应标明行为由谁负责、承担什么职责，以及包含哪个概念或操作。模型和服务可以有同一个所有者；它们不必放在同一个文件中。

选择边界时应用 codebase-design：将每项能力集中在一起，仅在拆分有助于理解时才拆分。角色目录用于组织有用的模块；不要求每个辅助函数、查询、类型或步骤都单独成文件。

将此方法应用于请求涉及的范围。规划请求会生成计划；实施请求则授权进行相关结构调整。本技能本身不授权安装、升级依赖项或更改其他仓库。

以事实为依据开展工作

阅读目标仓库的说明、包指南、已接受的决策、清单、导出/导入映射和验证脚本。在分配角色前检查实际源代码及其调用方。将现有计划视为设计依据，并根据当前工作树核对其中的清单和执行声明。

识别现有所有者、公共接口、组合根、测试策略、生成输入和框架命名要求。区分已验证事实与建议路径。对于整个项目的工作，考虑每个包和应用，包括有意保持不变的部分。

遵守用户和仓库的明确约束。根据代码确定常规布局选择；仅在尚未解决的所有权或契约选择会实质性改变请求结果时才提问。

选择所有者

• 专注型包可以作为所有者：src/models/Invoice.ts 和 src/services/InvoiceStore.ts 归属同一所有者。
• 包含多个重要领域的包应先按领域分组： src/billing/models/Invoice.ts、src/billing/services/InvoiceStore.ts。
• 将应用的屏幕、路由和特定功能行为保留在应用中。 可复用 UI 应放在独立包中；从工作区中查明该包的名称和别名。不要将应用路由、存储和 API 客户端放入其中。
• 根据实际所有者和调用方，为共享基础设施确定归属。仅名称相似不足以成为合并能力或创建另一个包的理由。
• 区分领域 models/ 与 AI 模型提供商能力。后者应按其实际职责命名，例如 inference/ 或 providers/，不要在未说明的情况下更改其公共契约。

将包构建为公共接口精简的深层模块。避免每种类型或服务都单独建一个包。仅在有实用代码归属其中时才创建角色目录；已有精确角色时应保留，不要创建空目录结构。

按职责分配角色

角色	内容和边界
models/	模式、派生类型、ID、值对象和密切相关的纯操作。将模式及其派生类型放在一起。
services/	具名能力以及针对所需接口的操作。通过组合接收具体实现。
adapters/	数据库、HTTP、SDK、文件系统、宿主和框架实现，包括特定提供方的解码。
workflows/	协调服务的流程；由组合根选择具体适配器。
policies/	依赖领域概念的业务决策和验证规则。
mappers/	在既有表示形式之间进行的、可独立使用的转换。将适配器私有的行转换与其操作放在一起。
utils/	独立于领域契约的小型辅助函数。了解领域的辅助函数应归入相应的模型、策略或映射器。

当其他角色有助于说明代码时，可使用 config/、tools/、prompts/、 components/、hooks/、state/、routes/ 或 runtime/。配置结构 和默认值应与凭据及实时资源构建分开。应用入口应保持精简，并将实时组装放在组合根中。

移动混合模块前，应先阅读其内容。文件名不能证明函数是纯函数，也不能将服务契约与其具体实现分开。拆分职责清晰的部分，同时保持行为不变；如有必要进行语义变更，应将其作为单独的变更。

如果某项操作的私有辅助函数、查询、绑定和解码必须结合理解，就应将它们保留在本地。只有当映射器或辅助函数能够隐藏有意义的决策，或确实供调用方使用时，才应共享；不要仅为缩短另一个文件而共享。保留已配置的行数限制，并为职责内聚的模块记录狭义例外。

统一模块命名

这些默认约定优先服从用户的明确选择，以及仓库或框架中既有的约束。目录所有者的大小写应与仓库保持一致；角色目录使用小写复数形式。

类型	默认约定	示例
命名模型、架构、服务或工具包	PascalCase	Invoice.ts、InvoiceStore.ts、BillingTools.ts
命名适配器	PascalCase 主体，可选小写实现后缀	InvoiceStore.postgres.ts
组件或 JSX 模块	PascalCase	InvoiceTable.tsx
函数、工作流、策略、映射器、处理器	kebab-case	issue-invoice.ts、parse-row.ts
React 钩子	camelCase	useInvoice.ts
配套测试或固定数据	源文件主体，小写后缀	InvoiceStore.test.ts、parse-row.fixture.ts

约定俗成的文件名应保持易于识别并使用小写：index、app、main、 agent、cli、config、errors、constants、types、schemas、fixtures、 testing、setup 和 runtime。目录应赋予它们明确且狭义的含义。 在有帮助时，按所属概念拆分宽泛的 types.ts，而不是为每个别名都拆分。

PascalCase 用于标识命名模块；它既不意味着该模块是类，也不意味着它只包含一个导出。将相关的架构/类型对和有用的关联导出放在一起。移动文件时，保留既有的导出名称拼写和服务标识。

小写点分隔后缀用于区分实现和测试角色。通过有限例外，保留框架路由、配置文件、声明文件、迁移编号、SQL、脚本，以及生成或由注册表管理的名称。 将职责不同的普通辅助文件移出组件目录。

当至少三个同级实现模块重复使用相同前缀来命名同一概念时，应为该概念创建子目录，并从文件名中移除前缀：

composer-attachments.ts → composer/attachments.ts
composer-images.ts     → composer/images.ts
composer-text.ts       → composer/text.ts

将分组保留在所属目录和角色目录之内，例如 utils/composer/text.ts，并对缩短后的名称应用上述大小写约定。只统计不同的实现模块；配套测试和固定数据应遵循其源文件的命名。若名称中的词语本身描述操作，则保留描述性操作名称，例如 parse-row.ts。

保留公共边界

如果某个包包含 src/，就将实现保留在其中，并使用精简、明确的公共入口文件，遵循仓库的导出策略。应暴露小型接口，而不是通过通配符导出私有目录树。仅包含模型的入口不应同时引入具体适配器。

公共接口应暴露完整操作，并负责其执行顺序、失败处理和清理。精简的公共重新导出可以确立这一边界；内部转发链通常只会增加导航成本。在真实的适配器边界转换外部执行模型，并验证传入数据。

遵循目标项目的兼容性策略：需要保留稳定公共模块标识符时就予以保留；必须移除过时路径时，更新所有调用方并移除这些路径。不要添加一刀切的兼容性包装器。公共资源和生成资源需要单独处理导出，而不是套用源文件命名规则。

在 Effect 项目中，定义 Agent 基础设施类型或服务之前，先检查已安装的 Effect Agent 合约目录和已发布的上游合约。如果存在上游合约，就导入该合约；组织层面的工作并不能成为重复定义沙箱、持久化、审批或工作流合约的理由。

规划或实施

对于规划、全项目重组或分阶段推出的请求，请阅读 references/planning.md。将所请求的计划保存在目标项目的 docs/ 中，即使可复用预设位于共享仓库中也是如此。规划以该文档为结束；提议的迁移不构成已执行的证据。

获准实施后，每次迁移一个职责明确的模块。同步更新其导入、公共导出、私有别名、构建根目录、测试发现和资源。让源文件扩展名与别名目标相匹配；追加扩展名的映射不得将导入路径变成 Invoice.ts.ts。必要时通过中间路径进行仅大小写不同的重命名，以确保 Git 能可靠记录。

保持运行时行为、模式、线格式、持久化键、服务标签、工具名称和工作流标识稳定。使用仓库现有的测试和检查来验证迁移后的公共接口和运行时资源。遵循仓库的测试放置策略，不要强行采用新的测试目录树。

评估、添加或声称已实施文件名／依赖项强制规则时，请阅读 references/enforcement.md。运行实际选定的检查，并验证图覆盖范围，再描述已强制执行的范围。报告变更路径、已验证的检查、剩余缺口，以及无关失败的准确命令和第一条可采取行动的诊断信息。