code-architecture

Files (2)

• SKILL.md
• examples.md · references/

SKILL.md (first lines)

# 代码架构（Code Architecture）

以面向对象设计（OOD）的职责封装和明确协作为基础，用项目现有语言、框架和约定表达。目标是让人看懂功能位置、对象职责、依赖和数据流；不要求固定目录、层数或全部使用类。

## 分层与职责

先读当前任务相关的规则、源码、调用方和测试，确认业务与数据归属，再映射到项目结构。

| 职责 | 常见位置 | 提供什么 |
|---|---|---|
| 领域模型（Domain） | domain、model | 业务实体、身份、关系和自身规则 |
| 应用服务（Application） | service、application | 用例、跨对象检查、操作顺序和事务范围 |
| 数据访问（Persistence） | repository、mapper、dao、persistence | 数据读取、映射、写入和存储兼容 |
| 基础设施（Infrastructure） | infrastructure、adapter | 文件、Git、进程、消息和外部系统等技术操作 |
| 接口入口（Interface） | controller、handler、cli | 参数解析、协议校验、应用调用和响应转换 |
| 对象装配（Composition） | module、configuration、bootstrap | 创建对象、注入依赖和注册入口 |

模块按业务或能力归属组织，各层通过明确对象、函数或接口协作。业务数据存取归所属模块；通用技术能力不接管业务规则。保持唯一业务写入责任，避免循环依赖和通过万能对象暴露全部内部方法。

## 对象与类型

- 值对象（VO）、数据传输对象（DTO）通常在所属业务层对象内定义为内部类型；语言不支持时放在同一文件内。
- 自定义 SQL、联表和聚合查询的映射对象，通常在所属数据访问对象内定义；需要时转换为应用结果。
- 业务实体、存储记录和接口结果按实际语义区分；不机械增加相同字段的镜像对象。
- 类型被多个独立能力共同维护，或协议、独立维护确有需要时，再单独成文件；公开方法中的类型保持必要可见性。VO 的具体含义沿用项目约定。

## 文件拆分与合并

优先在同一文件内用对象方法、私有函数和局部类型组织相关行为。除语言、框架和公开协议要求外，拆文件主要依据以下两点：

1. 能力具有重要、稳定的地位，需要隔离维护。
2. 文件体量与复杂度已妨碍阅读和修改，存在清楚的维护分界。

不按行数设统一阈值，也不因为有独立逻辑单元就拆文件。同一应用可包含创建、查询和修改；必要时才按查询/命令（Query/Command）等维度拆分。多个小文件总要一起阅读修改、主要负责转发时，考虑合并。

层边界调整可以是移动代码或内部重组。共享能力必须有真实复用和一致语义；小工具可以在一个文件内分组，无须预建完整分层目录。

前端按领域组织页面和完整交互组件。表单可包含自己的字段、状态和提交；单页短钩子（Hook）可留在页面内，真实共享逻辑再独立。跨领域宿主负责装配，不为每个组件机械配套类型、状态、钩子和客户端文件。

## 代码地图与验证

开发中的职责、路径或关系变化影响已有知识时，主动说明影响与校准建议；未授权知识维护时等待相关授权，已有授权不重复询问。按授权范围采用 `current-knowledge-maintenance` 更新相关表达；制作地图时采用当前可用的 `code-map`。普通开发没有规范变化不因此强制建立 OpenSpec 变更；无影响项说明依据后保留，范围外缺口单独提出建议。

新功能优先扩展已有能力；重构说明具体阅读或维护问题；审查区分必要调整、可选优化和保留项。只处理当前授权范围，项目与用户明确约定优先。

结构设计、跨模块重构或用户明确要求完整地图时，输出相关目录树、所属层、主要对象、代表性方法和关键调用链。调整项说明现有位置、处理方式、原因与调整后功能，并区分当前与拟议结构。其他局部修改只说明相关位置和影响，不强制输出完整地图。

需要地图时，采用项目真实文件名和中英文职责说明；已有架构文档仅按实际结构变化就地维护。需要分层、内部类型或拆并案例时，按对应小节读取 [references/examples.md](references/examples.md)，不把示例当固定目录模板。

实施后核对调用、数据归属和副作用，运行适用的编译、类型及行为检查。存在地图时核对其与实现一致；发生拆并时确认维护成本降低。目录整齐、文件变短和静态检查通过不等于行为验证完成。

From BuildrAI/Buildr, MIT.

More from BuildrAI/Buildr