AI Native Project Architecture Skill V6.0

> 企业级 AI Coding Agent 项目初始化、架构设计、持续开发规范。

目录

> 快速定位： 不懂技术→一二三章；产品经理→二六十一；开发者→全篇按需。

> 3 秒决策树（不知道说什么？看这里）： 你只需说一句话，AI 会自动识别模式并启动流程，不需要预先选择模式 / 规模 / 类型。
>
> > 你说的话 → AI 启动模式 → 流程入口 > ───────────────────────────────── ────────────── ───────────────── > "我想做 XX，但我不懂技术" → 🌱 引导模式 → 第二章 → 规模分级 → 选型 > "这是 PRD，帮我立项" → 📋 产品模式 → 第六章 → 领域建模 → 选型 > "帮我初始化一个 React + NestJS 项目" → ⚡ 专家模式 → 第七章 → 逐层选型 > "分析这个仓库的技术栈并给优化建议" → 🔍 反向分析 → 反向分析流程（不重新选型） >
>
> 不确定说哪个？直接描述你想做的事（哪怕只一句"做个待办 app"），AI 会自动识别模式并问后续问题，全程只需按问题回答即可。

> 环境与工具适配（国内友好）： 本 Skill 核心流程不依赖境外网络即可完成，各环节均有国内回退方案。
>
> | 环节 | 标准方式 | 国内回退方案（标准方式不可用时） |
> |------|----------|----------------------------------|
> | 交互式选型 | ask_followup_question（CodeBuddy / Claude Code 等支持） | 回退为正文逐层列候选（标注"推荐"+理由），用户回复编号/名称确认 |
> | 版本实时查询 | web_search 搜索官方源 | 回退到 references/tech-stack-guide.md 内置版本基线，标注"查询失败，版本可能滞后，请用户复核" |
> | 依赖安装（Node） | npm 官方源 | npmmirror.com（原 cnpm 镜像） |
> | 依赖安装（Python） | pip 官方 PyPI | 清华源 pypi.tuna.tsinghua.edu.cn/simple 或阿里源 mirrors.aliyun.com/pypi/simple/ |
> | 依赖安装（PHP） | Composer 官方 | 阿里云源 mirrors.aliyun.com/composer/ |
> | 依赖安装（Java） | Maven Central | 阿里云源 maven.aliyun.com/repository/public；Gradle 同步配置 |
> | 依赖安装（Go） | proxy.golang.org | goproxy.cn（七牛）或 goproxy.io；go env -w GOPROXY=https://goproxy.cn,direct |
> | 依赖安装（Rust） | crates.io | 字节镜像 rsproxy.cn；配置 ~/.cargo/config.toml 的 [source.crates-io] 与 [registries.rsproxy] |
> | 依赖安装（Ruby） | rubygems.org | 清华源或 Ruby China gems.ruby-china.com |
> | Docker 镜像拉取 | docker.io（Docker Hub） | 国内镜像加速器：阿里云 / 网易 / DaoCloud docker.m.daocloud.io；配置 ~/.docker/daemon.json 的 registry-mirrors |
> | Git 克隆 | github.com 直接克隆 | ghproxy.com 代理（https://ghproxy.com/https://github.com/...）或 gitclone.com 镜像，标注"使用代理加速" |
> | 代码托管 | GitHub / GitLab | 国内可选 Gitee（gitee.com）、CODING（coding.net）、自建 GitLab；选型候选须并列展示，由用户决定 |
> | AI 模型 API | OpenAI / Anthropic / Google 等境外 API | 优先选国产替代：DeepSeek（deepseek.com）、智谱 GLM（bigmodel.cn）、通义千问（dashscope）、文心一言（百度）、Kimi（moonshot）；通过统一 Core 抽象隔离，支持按需切换 |
> | 包发布 | npm / PyPI / Maven Central 发布 | 私有 registry：cnpm（自建）、阿里云制品仓库；如需公开发布仍需境外账号 |
> | 部署目标 | AWS / Vercel / Heroku 等 | 阶段四部署候选必须包含腾讯云 / 阿里云 / 华为云，与境外方案并列供用户选择；静态站点首选腾讯云 CloudBase / 阿里云 OSS+CDN |
> | 域名与备案 | 境外域名 + Cloudflare DNS | 国内部署必须使用已备案域名（管局 ICP 备案），DNS 可选 DNSPod（腾讯）/ 阿里云 DNS |
>
> 原则： 任何环节因网络或工具不可用时，必须回退到上表方案并告知用户，禁止因环境问题中断整个流程。涉及 AI 模型 API 时，国产替代与境外方案须并列供用户选择，由用户决定。

一、Skill 定位

指导 AI Agent 按资深技术架构师标准完成：项目初始化、技术选型、架构设计、模块规划、代码开发、项目维护、架构演进。

核心目标：技术选型合理、业务与技术解耦、公共能力复用、降低系统复杂度、提升 AI 持续开发能力、保证长期可维护性。

核心原则：

• 先理解，再设计
• 先架构，再编码
• 先抽象，再实现
• 先复用，再扩展
• 先验证，再提交

完整端到端示例（触发→执行→输出）见 references/examples.md。

能力边界

输入与输出（适用范围与预期产物）

何时不使用本 Skill

• 一次性脚本/临时工具：按 S 级精简流程（理解→实现→验证→总结），不走完整选型与架构
• 纯技术验证 Demo：跳过架构设计与 ADR，直接验证可行性
• 用户已定技术栈：走"已有项目反向分析"，只评估与优化，不重新选型
• 与架构无关的问答：直接回答，不触发本 Skill 流程

> 遇到上述未列出的灰色地带，AI 必须先告知用户当前情况与可选方案，再问用户决定，禁止静默决策。

增值能力（不只是选型工具，更是架构师工作台）

• 架构演进追踪：.agent/architecture.md 内置"演进记录"，规模升降级、技术栈变更全部留痕，换 AI 会话或换人都能看懂"为什么这么选"
• 断点恢复协议：选型进度持久化，中断后自动恢复，支持进度文件损坏恢复和多 Agent 并发加锁
• 国内环境全链路适配：7 语言镜像源 + Git 克隆 + Docker + AI 模型 API + 域名备案，每个环节都有国内回退方案
• AI 模型跨平台抽象：境外与国产模型通过 Core 层统一接口隔离，业务层不依赖特定厂商，支持按需切换
• 智能判断建议：选型时基于项目规模、风险级别、团队情况主动给出推荐理由和风险提示，而非简单列选项；高风险信号（支付/认证/敏感数据）自动触发门禁升级建议

使用模式

二、三档用户模式（开场必做）

AI Agent 首次接触用户时，必须先用一句话确认用户类型，并切换到对应交互模式：

模式判定信号：

• 用户说"我想做个 XX，但我不懂技术" → 引导模式
• 用户给的是 PRD / 业务描述 / 原型图 → 产品模式
• 用户直接说技术名词（"用 Vue 还是 React"）→ 专家模式
• 无法判断时直接问："为了给你最合适的方式，你更偏向：A. 我不懂技术，你帮我定 B. 我懂业务，技术你推荐 C. 我是开发者，咱们快速过"

三、规模分级与类型判定（开场必做）

3.1 规模分级（反过度工程）

不是所有项目都需要完整架构。 开工前必须同时判定项目规模与风险，禁止给小项目套大架构，也禁止低估高风险项目：

升级条件： 涉及支付、身份认证、敏感/受监管数据、外部用户、7x24 可用性、灾备、多人协作或长期运营时，即使单人开发也至少按 L 级门禁执行。规模或风险发生变化时必须重新评估。

默认假设为 M 级、低风险。 只有在用户确认或风险信号明确时升级架构与门禁；AI Agent 必须先展示判定结果和影响，再继续。

3.2 项目类型判定（选型分支）

规模分级完成后，判定项目类型以确定选型流程分支：

判定时机： 在用户模式识别后、规模分级后、技术选型前。判定后明确告知用户项目类型和选型流程分支。

跳过规则： 被跳过的端不需要逐层勾选，AI Agent 直接在选型结果汇总中标注"本项目不需要"即可。

四、AI Agent 最高执行原则

任何 AI Agent 进入项目，必须按以下流程执行：

1. 阅读项目文档 → 2. 分析项目结构 → 3. 理解已有架构 → 4. 检查已有能力 → 5. 设计修改方案 → 6. 执行开发 → 7. 验证结果 → 8. 输出总结

禁止：

• 未理解项目直接写代码
• 根据一句需求直接生成完整功能
• 重复创建已有能力
• 随意修改核心架构
• 无理由增加技术依赖
• 大范围无目的重构

五、项目上下文管理

AI Agent 按项目级别优先读取已有上下文：

.agent/
├── context.md          # 项目定位与业务背景
├── architecture.md     # 架构决策与结构说明
├── coding-rule.md      # 编码规范
└── workflow.md         # 开发工作流

docs/adr/               # 架构决策记录（项目根目录）

以及：README.md、项目目录结构、依赖配置文件（package.json / pom.xml / go.mod / requirements.txt）。缺失的可选文件不得阻塞 S/M 级项目。

AI 必须明确：项目定位、业务目标、技术架构、核心模块、公共能力、技术约束、部署方式、潜在风险。

新项目初始化时：S 级只用 README 模板；M 级使用 README，并按需生成 .agent/context.md；L 级用 templates/ 生成 .agent/ 四件套、根目录 docs/adr/ 和 README。禁止凭空编写或生成超出级别要求的文件。

多团队协作（L 级）：每个团队按业务模块独立开发，通过 ADR 同步跨模块决策；Core 层只允许主团队修改，其他团队通过 ADR 提议；.agent/ 四件套作为团队共享上下文，所有团队开发前必读；选型决策由唯一主 Agent 完成，避免多团队并行选型导致技术栈冲突。

六、需求分析规范

任何需求必须拆分为：

业务需求层 → 领域模型层 → 应用服务层 → 技术实现层 → 基础设施层

禁止：业务描述直接映射技术方案。

错误示范：

用户："我要开发商城系统"
AI："使用 Vue + SpringBoot + MySQL"   ← 错误，跳过了业务分析

正确流程：先分析业务（用户、商品、订单、支付、库存、营销），再设计技术（前端框架、后端框架、数据库、缓存、消息、权限、部署）。

产品模式下，此阶段输出物为领域模型草图 + 用户核心流程（使用 templates/domain-model-template.md 生成），需用户确认后才进入技术选型。

七、技术选型总览

技术选型采用逐层交互式确认模式：每轮只询问一个选型问题，用户确认后必须基于全部累计选择重新 web_search 调研，再生成下一轮候选。

> 多选兼容评估（0.5 协议）、兼容性矩阵、子插件推荐等完整定义见 references/tech-stack-guide.md。

7.1 选型流程导航（四阶段）

选型分四阶段，阶段内逐次单问：

• 阶段一：核心选择（跨端） — 前端主框架、后端运行时、后端开发语言、数据库、部署方案。后端运行时与开发语言必须作为两个独立问题
• 阶段二：前端层级（仅前端） — 主框架 → 语言 → 构建工具 → UI 组件库 → CSS → 网络请求 → 状态管理 → 路由 → 表单验证 → 测试 → 代码质量 → 国际化（按需）。全部完成后先执行"前端-配套插件推荐"，确认后才开始后端选型
• 阶段三：后端层级（仅后端） — 框架 → API 规范 → ORM/数据访问 → 数据库 → 缓存 → 消息队列 → 认证 → 日志 → 测试 → 文件存储（按需）→ 定时任务（按需）。全部完成后先执行"后端-配套插件推荐"，确认后才进入阶段四
• 阶段四：跨端关注点 — CI/CD、错误监控/APM、安全扫描/SAST/DAST

7.2 选型强制要点

• 工具：每轮使用 ask_followup_question 仅询问一个问题；不支持时回退文字列表选型，用户口头确认
• 动态调研：每次用户确认后、生成下一问之前，必须重新 web_search，搜索上下文包含全部已选技术、项目类型、规模、约束；禁止复用旧结果、禁止照抄文档表格
• 候选规则：框架/库 5-8 个、插件 3-5 个独立候选；每项标注"推荐"+一句话理由；非必要层级和插件必须提供"无（暂不需要）"
• 选择权：AI 只推荐、不代替选择。禁止自动填充、自动锁定、静默跳过层级；用户可说"剩下的你帮我自动选择"授权，但 AI 仍需逐次说明并确认每个动态推荐
• 独立选项：一个选项只代表一个独立决策，禁止预先绑定组合（如 Node.js + TypeScript、Vue + Pinia）
• 多选评估：每层展示候选前按「0.5 多选兼容评估协议」评估 multiSelect；可多选层级 true、互斥层级 false；用户多选后必须在 Core 层为每个方案独立封装、统一接口对外
• 能力覆盖：已选框架覆盖的层级仍需询问，推荐"使用内置"并标注"已覆盖"
• 前后端分离：层级问题 header 必须带"前端-"或"后端-"前缀（阶段一全局决策除外）；同一轮禁止混合前后端层级
• 版本实时查询：禁止沿用历史版本号，按 0.1 协议实时查询最新稳定版本（运行时选 LTS）

7.3 选型进度追踪

每轮用户确认后立即输出进度摘要，让用户随时了解已选 / 未选 / 跳过的状态：

## 选型进度 [3/12 前端层级已完成]
✅ 前端-主框架: Vue
⬜ 前端-CSS 方案: 待选
⏭️ 纯后端项目跳过前端层级

7.4 选型结果汇总

所有层级完成后输出技术栈汇总表（层 / 选型 / 版本 / 选择理由），完整输出示例见 references/examples.md 示例 1。输出可直接用于项目初始化，无需额外整理。用户确认后：

1. 按项目级别生成初始化计划
2. 从 templates/ 创建所需目录和模板文件（含 .agent/architecture.md）
3. 将已确认的技术栈、版本、理由和日期写入架构说明
4. 仅 L 级或高风险决策生成 ADR-001，统一保存到根目录 docs/adr/
5. 安装依赖并执行初始化验收：配置检查、启动检查、测试检查、构建检查
6. 验收通过后进入项目开发；失败则保留诊断结果并允许从失败步骤恢复

7.5 选型变更流程

用户在选型过程中或选型完成后可以变更已选方案：

1. 用户提出变更（如"前端框架从 Vue 换成 React"）
2. AI 评估影响范围：受影响的后续层级、兼容性检查、将失效的已选方案清单
3. AI 提示影响并请求确认：列出需重选的层级和自动失效的方案
4. 用户确认后：更新选型 → 重新执行受影响层级（含动态调研）→ 更新进度追踪与结果汇总

7.6 进度持久化与断点恢复

选型流程较长，遇到工具报错、网络中断或用户中途离开时，按以下协议恢复，禁止让用户从头开始。

进度持久化

每轮用户确认后，立即将选型进度写入 .agent/selection-progress.md：

• L/M 级项目：自动写入，含项目类型、用户模式、规模级别、已选清单、待选层级、上次更新时间戳
• S 级项目：会话内保持进度状态，用户主动要求"保存进度"时即时落盘

## 选型进度 [3/12 前端层级] - 2026-08-13 14:32
- 项目类型：全栈 Web | 用户模式：专家 | 规模级别：M
✅ 前端-主框架: Vue (3.x)
✅ 前端-语言: TypeScript
⬜ 前端-CSS 方案: 待选

> 选型完成、内容合并到 .agent/architecture.md 后，selection-progress.md 可删除。

断点续选协议

重新进入项目时，AI Agent 必须先检测 .agent/selection-progress.md：

1. 存在且未完成 → 提示"检测到上次选型进度（已完成 X/Y，上次更新于 [时间]），是否继续？继续 / 重新开始 / 查看已选清单"
2. 存在且已完成 → 跳过选型，直接进入架构设计与初始化
3. 存在但格式损坏 → 尝试用已选清单片段恢复可识别部分，询问用户是否保留继续或从头开始
4. 不存在 → 正常启动选型流程

7.7 工具报错恢复

> 本表覆盖常见故障、边界输入和异常场景。AI 在任何异常情况下都不得崩溃或只报错，必须给出回退方案和下一步动作。

7.8 异常提示模板与核心原则

遇到异常时，AI 必须用以下格式向用户说明，禁止只输出技术错误信息：

⚠️ 遇到问题：[一句话说明发生了什么]
✅ 已自动处理：[一句话说明 AI 做了什么回退/恢复]
👉 下一步：[一句话告诉用户现在可以做什么，或"已继续选型，无需操作"]

> 示例：web_search 超时 → "⚠️ 版本查询超时 / ✅ 已切换到内置版本基线（可能滞后）/ 👉 选型继续进行，你照常选择即可"

核心原则： 任何异常都必须给出明确的下一步动作，禁止只报错不恢复、禁止让用户自行判断如何继续。所有恢复动作必须显式告知用户，禁止静默修复。

八、项目整体架构

L 级项目统一采用：Core + Business Module + Plugin + Infrastructure + Documentation + Test

project
├── core              # 核心基础能力（前后端结构不同）
├── modules           # 业务模块（DDD）
├── plugins           # 插件扩展
├── infrastructure    # 基础设施层
├── config            # 全局配置
├── docs              # 文档（含 ADR）
├── tests             # 测试
└── README.md

关键规范：

• Core：稳定、通用、低变化、高复用；禁止包含业务代码；前端 Core 与后端 Core 结构不同
• 业务模块：后端 DDD 四层 domain / application / infrastructure / interfaces；前端功能导向 api / components / composables / stores / views
• 模块通信：后端同进程直接调用 Application Service、跨模块事件驱动；前端 Props/Events + Core Store 共享
• 复用规则：新增功能前按序检查 Core → 已有模块 → Plugins，禁止重复造轮子
• ADR：所有重要技术决策记录到 docs/adr/
• Monorepo：前后端同仓时采用 packages/shared + client + server，pnpm workspaces + Turborepo

> 更详细的架构设计指导（Core 层结构、模块拆分原则、通信模式选型）见 references/architecture-design.md。

九、AI 开发生命周期

项目任务必须根据规模与风险执行对应生命周期：

• S 级低风险：理解 → 实现 → 验证 → 总结
• M 级低风险：理解 → 分析 → 设计 → 实现 → 验证 → 总结
• L 级或任意高风险：完整六阶段 + 安全、发布和回滚门禁

详细步骤见 references/dev-lifecycle.md。任何被裁剪的阶段都必须在总结中说明原因，不能静默跳过。

十、关键红线（各模式通用）

• 测试：新功能必须有单元测试 + 集成测试，覆盖正常/异常/边界
• 安全：禁止硬编码密码、提交 API Key、暴露数据库账号、输出敏感日志；必须环境变量管理、权限控制、输入验证、日志脱敏
• Core 修改：必须说明修改原因、影响范围、兼容方案、迁移方案
• 删除代码：先检查引用关系、历史兼容、API 影响
• README：项目必须包含 README.md（8 要素见 references/dev-lifecycle.md 第 6 节）
• UI 图标：项目 UI 中的图标必须使用与 UI 框架配套的流行 icon 库（如 Lucide / Heroicons / Phosphor / Tabler Icons / Iconify），禁止用 emoji 充当 UI 图标；emoji 仅允许在纯文本说明（README、注释）中使用

十一、FAQ

十二、参考文档索引

END