project-folder-structure

项目文件夹结构

快速开始

对于非简单项目，先阅读本地规则，再使用附带的辅助脚本量化项目结构：

node scripts/structure-snapshot.mjs --root /path/to/project --max-depth 3

编辑前先提交审查结果：扫描范围、本地约定、不可更改的约束、拥挤区域、混合生命周期、含义模糊的名称、建议的组织轴、最小安全批次、迁移风险和验证命令。

核心规则

应用模式前，先尊重项目本身。良好的组织方式应让人们更容易理解、修改、测试、运维和归档项目，同时保留框架规则、公共契约、生成路径、持久化状态和本地约定。

工作流

1. 定义范围：工作区、仓库、软件包、应用区域、功能、文档树、数据／制品区域或混合单体仓库。
2. 阅读本地事实：AGENTS.md、CLAUDE.md、README.md、CONTRIBUTING.md、CONTEXT.md、文档、ADR、清单、CI、部署配置、脚本和现有的整理规范说明。
3. 提出结构建议前，先找出不可更改或高风险路径：框架约定路径、公共 API、软件包导出、路由、CLI 命令、迁移、生成的客户端、部署路径、持久化制品、运行时状态、机密信息和外部使用方依赖的路径。
4. 运行 scripts/structure-snapshot.mjs 或同等的只读名称／数量扫描。不要检查机密内容。
5. 按组织轴分类当前文件夹：外部约束、概念／能力、变更模式、受众／使用方、制品生命周期、所有权、状态或工具链层。
6. 选择最符合项目理解和变更方式的组织轴。除非本地或外部约束另有要求，否则应让经常一起变更的文件彼此靠近。
7. 提出最小的有效批次：一个拥挤的文件夹、一个概念、一次生命周期拆分、一个软件包、一次工作区清理，或一次文档／资源迁移。
8. 编辑前，说明哪些内容将移动、哪些内容保持稳定、会保留哪些包装层或重定向，以及如何确保兼容性。
9. 编辑后，更新导入、CLI 路径、文档、测试、软件包／配置引用、生成的清单、CI 和架构防护规则。
10. 使用项目原生检查、针对性测试、旧路径搜索，以及可用时的 git diff --check 进行验证。

决策规则

• 当工作按产品领域、领域术语、用户工作流、可复用组件或稳定职责变更时，使用概念／能力文件夹。
• 当使用方需要在小型、可互换的工具、适配器、模板、插件、策略或示例中进行选择时，使用工具箱文件夹。
• 当源文件、测试、文档、资源、生成文件、运行时状态、报告、数据集、实验、归档或临时工作具有不同的保留规则时，使用生命周期文件夹。
• 当公共示例、SDK 接口、运维脚本、内部实现或贡献者文档需要各自独立的位置时，使用受众文件夹。
• 在工作区层级组织内容时，使用状态文件夹：活跃、已归档、外部、分叉、实验、已弃用，或按客户端／项目所有权划分。
• 仅当语言、框架、构建工具、部署目标或贡献者工作流使其成为最清晰或必需的结构时，才使用分层／工具链文件夹。
• 避免使用 helpers、services、managers、misc 和 utils 这类仅按类型划分的目录，除非它们会掩盖实际概念，或迫使无关文件放在一起。
• 保持入口点精简且稳定。如果外部调用方、软件包脚本、URL、cron 作业、用户习惯或持久化路径依赖旧位置，就将实现移至入口点之后。
• 除非项目对此有明确说明，否则不要将生成文件、运行时输出、缓存、临时文件和大型制品输出放在源文件夹中。
• 默认不要删除。优先采用迁移计划、归档／隔离路径、保留规则，或征得用户明确同意。

审批关卡

出现以下任一情况时，应用前请先征求同意：

• 一次要移动多个领域／软件包／工作区区域。
• 公共导入、路由、CLI 命令、软件包导出、URL、cron 负载、数据路径或持久化产物路径发生变化。
• 此次移动涉及机密信息、身份验证配置、部署配置、迁移、数据库状态、生成内容保留、备份或大量数据。
• 本地惯例与工具／框架文档相冲突。
• 理由主要出于美观，而非有证据支持的可维护性考量。

输出格式

使用以下精简格式：

## Structure Audit
- Scope scanned:
- Local rules read:
- Immovable constraints:
- Current organizing axes:
- Crowded or mixed-lifecycle areas:
- Ambiguous/generic folders:

## Proposed Batch
- Organizing axis:
- Move:
- Keep stable:
- Wrappers/redirects:
- Docs/config to update:
- Risks:
- Verification:

详细原则请参阅 REFERENCE.md。项目类型指南请参阅 PROJECT_TYPES.md。移动表格示例请参阅 EXAMPLES.md。