AI 项目架构搭建

要解决什么问题

当 AI 编程代理接手一个新项目时，最常见的失败模式是：直接生成一堆业务代码，然后在"tech debt"和"over-engineering"之间反复横跳。更具体地说：

• 项目刚建起来就引入了生产级中间件、多模块分层，结果代码量比需求还大。
• 技术选型时没有分层确认机制，AI 自动锁定某个框架，事后才发现和团队技术栈冲突。
• 需求、领域模型、架构设计之间没有明确的输出物边界，Agent 在头脑里完成了本应留档的推理过程。
• 国内网络环境下依赖安装、Git 克隆、模型 API 频繁失败，Agent 通常只会报错然后停住。

这个技能把资深架构师的决策流程显式化为 Agent 可以执行的步骤和产物，而不是让模型自由发挥。

技能如何工作

• 三档用户模式 + 规模分级：开场先确认用户画像（小白 / 产品 / 开发者）和项目规模（S/M/L），避免给脚本套微服务架构，也避免给高风险支付项目用最简流程。
• 四阶段技术选型：按核心选择 → 前端层级 → 后端层级 → 跨端关注点逐层推进。每轮只问一个问题，每个选项都标注 推荐 + 一句话理由，用户显式确认后才进入下一层。
• 断点恢复与进度持久化：选型进度写入 .agent/selection-progress.md，会话中断后新 Agent 可以自动检测并继续，不用从头再来。
• 架构与生命周期规范：L 级项目统一采用 Core + Business Module + Plugin + Infrastructure + Docs + Test 结构，开发任务按规模分级走对应生命周期，所有裁剪都要在总结里说明原因。
• 国内环境全链路适配：npmmirror、pypi.tuna.tsinghua.edu.cn、goproxy.cn、rsproxy.cn、阿里云镜像、ghproxy.com 等都有明确的回退路径，任何环节失败都会自动降级而不是中断流程。

适用边界

• 不写具体业务代码，不替代人工架构评审，不做线上运维和故障排查。
• 已有明确技术栈的项目走"反向分析"路径，只评估和优化，不重新选型。
• 一次性脚本或纯技术验证 Demo 按 S 级精简流程走，跳过架构设计和 ADR。
• AI 模型 API 选型必须由用户确认，境外方案和国产方案并列展示，禁止静默选择。