基础支撑
模块存在意义
在大规模 TypeScript 仓库里，真正决定维护成本的往往不是业务页面，而是基础支撑层。Claude Code 的utils/、types/、constants/、migrations/ 正在承担这类底板责任。
关键文件与入口
| 文件/目录 | 作用 |
|---|---|
src/utils/ | 通用工具函数、权限判断、shell、git、日志、模型、配置等横切能力。 |
src/types/ | 通用类型定义，稳定不同模块之间的数据约定。 |
src/constants/ | 常量与配置项入口。 |
src/migrations/ | 处理配置和历史兼容迁移。 |
对上游 / 下游的依赖关系
- 上游：几乎所有业务模块都会调用这一层。
- 下游：同样服务于几乎所有业务模块。
运行时扮演的角色
- 提供权限、shell、git、用户配置、模型能力判断等复用逻辑。
- 维持跨模块一致的数据结构与常量语义。
- 在版本演进时兜住旧配置与新行为之间的兼容。
新读者建议的阅读顺序
- 与当前问题最相关的
src/utils/子目录 - 对应的
src/types/ - 相关
src/constants/ - 如果涉及行为升级，再看
src/migrations/
为什么不建议一开始就深挖这里
- 这里体量最大，但不是建立全局结构的最佳入口。
- 只有在你已经知道主流程之后，基础层的意义才会非常清晰。
- 它更适合带着问题来读，而不是一上来通读。