optimize-repo-structure

name	optimize-repo-structure
description	分析 Git 仓库结构并提出优化建议。适用于发现大文件过长、模块职责混杂、目录层级不清、重复逻辑散落、模块边界模糊、import 耦合异常等问题；只输出结构优化建议、最小下一步和验证方式，不直接执行重构。

Optimize Repo Structure

把仓库结构当作可维护性的公共接口来处理。先建立结构地图，再基于证据提出建议；即使范围清楚、风险可控、验证可运行，也只输出小步重构方案，不直接改文件。

读取顺序

1. 先读仓库根目录的 AGENTS.md，如果存在。
2. 读取结构文档：docs/repo-structure.md，或仓库已有结构文档。
3. 阅读项目入口和配置，例如 README.md、package.json、pyproject.toml、Cargo.toml、go.mod、Makefile、CI 配置、路由或应用入口。
4. 使用 rg --files、git ls-files、语言工具或测试配置建立真实目录视图。

诊断维度

优先关注会影响开发速度、理解成本或变更安全的问题：

• 大文件或超长模块：文件承担多个抽象层、多个业务场景或大量不相关 helper。
• 职责混杂：UI、数据访问、领域逻辑、API、状态管理、脚本和测试边界混在一起。
• 目录层级不清：目录名不能表达职责，或者同类模块分散在多个位置。
• 重复逻辑散落：相似转换、校验、请求封装、常量或测试夹具被复制。
• 模块边界模糊：跨层 import、循环依赖、从内部路径绕过公共入口。
• 入口和产物混乱：生成物、构建输出、实验代码或 vendor 代码混入源码判断。

输出建议

默认只输出建议，不改文件。建议应包含：

• 问题摘要和证据：文件路径、目录、行数、依赖或重复模式。
• 影响：理解成本、变更风险、测试困难、复用困难或发布风险。
• 推荐结构：目标目录、模块职责和边界规则。
• 最小下一步：一个可独立 review、可验证、可回滚的小改动。
• 风险和验证：需要运行的测试、类型检查、lint 或手工检查。

小步重构方案

生成方案时，按以下约束行动：

1. 先检查 git status --short，把已有改动视为用户所有，并在建议里标注相关风险。
2. 一次方案只处理一个清晰结构问题，例如：
   • 从大文件中抽出纯 helper、常量、类型或局部组件。
   • 把低耦合工具函数移动到更贴近职责的模块。
   • 建立或收紧模块公共入口，并列出需要更新的内部 import。
   • 整理测试夹具或共享测试 helper 的位置。
   • 移动文件后需要同步的 README、结构文档和路径引用。
3. 保持公共行为不变。需要改变公共 API、路由、数据模型或持久化行为时，明确风险和额外验证。
4. 不建议移动 .git/、依赖目录、构建输出、缓存、生成物、vendor 代码或外部同步目录。
5. 对 import 更新，建议使用语言原生工具、类型检查或测试验证，不依赖肉眼批量替换。
6. 列出最小相关验证；影响面大时扩大到类型检查、lint 或测试套件。

不做的事

不要直接编辑、移动、删除、重命名文件，不要直接拆分模块、改 import、提交代码或写结构文档。不要在一次建议里做大范围架构重写、命名审美调整、跨业务模块搬迁、删除历史兼容入口，或把结构建议伪装成已经验证的事实。

结束前

报告：

• 建议调整哪些结构边界；
• 建议移动、拆分或更新哪些文件；
• 推荐运行哪些验证命令；
• 是否建议继续运行 $sync-repo-structure-doc 生成结构文档更新建议。