AI 新建项目 目录结构基础 约束

[四折光曲]

1. 先定边界，再做实现。
   明确目标、不做什么、完成标准；新增需求先判断是否属于核心职责，能通过扩展解决的能力优先外置。

2. 共享事实只维护一份。
   版本、限制、协议等共同依赖的信息应有唯一权威来源，其他位置通过引用或生成获取，避免人工同步。

3. 按变化原因划分模块。
   经常一起变化的逻辑放在一起，独立变化的逻辑分开；入口负责组织调用，模块各自承担清晰职责。

4. 让依赖、状态和生命周期显式可见。
   减少循环依赖与隐式全局，明确启动、停止、连接和清理过程，使状态可查询、问题可定位。

5. 先定义契约，也定义失败。
   对外接口应明确输入、输出、错误、资源限制与兼容性；调用方应能区分执行失败、尚未完成和已经生效。

6. 把重复约束变成自动检查。
   能生成的内容不手改，能机械验证的一致性不依赖记忆；生成过程应可重复，写入失败不能破坏已有内容。

7. 让文档各司其职。
   分清入门、设计、接口、验证和交接信息，同一事实避免重复维护；历史内容明确归档，随交付物提供的说明必须独立可用。

8. 让验证方式匹配真实风险。
   纯逻辑用快速测试，跨环境行为用真实集成验收，复杂交互辅以人工检查；简化环境中的通过不能替代用户环境中的证据。

9. 验证具体结果，也验证失败原因。
   不只检查是否成功，还要确认关键输出、状态变化和预期错误；区分环境未就绪与产品缺陷，让失败能够复现。

10. 把变更做成可审查、可交接的闭环。
    分开重构与行为变化，同步实现、契约、验证和说明；发布前核对交付内容，记录已知限制，并保留可追溯的版本。