文件结构和模块边界

这些是选择性的模式，不是每个项目都必须创建的空目录。优先保留与语言、框架和维护责任相符的现有布局。

小型应用、CLI 或静态站

project/
  AGENTS.md
  README.md
  src/                 # 按功能或框架约定组织
  tests/               # 若不与源码共同放置
  config/              # 仅在确有配置文件时建立

构建产物、真实密钥和运行数据不提交。单一工具或静态站不需要服务级目录结构。

独立服务

service/
  AGENTS.md
  README.md
  src/
    features/
    shared/              # 稳定小型原语，不作为杂物箱
    bootstrap/           # 组合依赖、启动应用
  tests/
    integration/
    e2e/                 # 确实有端到端检查时再建立
  docs/
    index.md
    architecture/
    api/
    data/
    plans/
    adr/
    operations/          # 只有实际运行服务时
  migrations/            # 有持久化 schema 时
  .github/workflows/     # 使用 GitHub Actions 时

在复杂功能内部可以按 domain、application、adapters、transport 分层。依赖方向应从入口和适配器指向应用规则，而不是让领域规则依赖数据库或 Web 框架。小服务不应为了层级图而增加空壳。

多服务单仓库

platform/
  apps/
    console/
    web/
  services/              # 仅包含有独立责任的可部署单元
  packages/
    contracts/           # 对外 schema，不放各服务私有 DB 模型
    sdk/
  infrastructure/        # 使用 IaC/编排工具时才建立
  tests/
    e2e/
    contracts/
  docs/
    product/
    architecture/
    api/
    data/
    security/
    operations/
    plans/
    adr/

单仓库不必对应一个部署单元；多个仓库也不自动要求微服务。先做边界清晰的模块化，再以独立发布、权限、维护责任、扩缩容或故障隔离等具体理由拆服务。

依赖方向和数据责任

每个能力把规则、输入、持久化和外部通信放在可识别的位置。共享包只承载稳定通用原语或版本化契约；不要把所有领域模型集中进一个全局 common 包。

服务通过拥有者的 API 或事件交互，不直接导入其私有内部模块或写其专属表。为重要数据标明权威存储、迁移责任、租户上下文、事务和留存。环形依赖、控制器中的业务规则和全局访问所有存储的单例都应谨慎审查。

Go、Python、SDK、研究项目和移动应用优先遵循各自生态的 src、cmd、internal、import 名称、工作区和框架目录约定。研究代码分清维护管线、探索 notebook、合成测试样本和受限数据。不要忽略被项目明确版本控制的研究输入。