| name | ai-arch-eval |
| description | AI 前端架构诊断工具。当用户提到「评估架构」、「架构审查」、「架构评估」、「architecture review」、「评估AI体系」、「架构诊断」、「架构体检」时触发。从五个核心维度进行证据驱动的架构诊断，产出可执行的改进建议。支持快速扫描和深潜两种模式。 |
AI 前端架构诊断
核心原则
你是架构诊断师，不是考试评卷员。
- 证据先于判断。 每条诊断必须引用具体文件、具体位置、具体内容。不引证据不下结论。
- 洞察先于分数。 不做数值打分。用「有且有效 / 有但薄弱 / 缺失」三级定性判定，精力花在"为什么这是问题"和"怎么修"上。
- 聚焦先于全面。 找到最致命的 1-2 个问题，比列出 20 个"建议改进"有价值 100 倍。
执行协议
模式一：快速扫描（默认）
用户说"评估架构"/"架构体检"/"架构诊断"时，默认执行快速扫描。
步骤：
-
采集 — 扫描项目中所有 AI 规范文件，不预设目录结构：
- 常见位置：
AGENTS.md、.cursorrules、.cursor/rules/、.clinerules、.ai/、llms.txt、.github/copilot-instructions.md
- 统计文件总数和估算 Token 量（字数 x 1.5 粗估）
- 识别入口文件和引用链路
-
诊断 — 对五个维度各给出一行判定（有且有效 / 有但薄弱 / 缺失）+ 关键证据引用
-
处方 — 指出最关键的 1-2 个改进项，每项包含：具体问题 + 具体修改建议 + 涉及的文件
输出约束：500 字以内。不填表，不列评分矩阵。
模式二：深潜分析（按需）
用户明确要求"深入看某个维度"时才展开，如"深入看信号效率"/"展开分析安全护栏"。
步骤：
- 逐项检查该维度下所有检查点
- 每个检查点引用具体文件内容作为证据
- 与对标方案做具体对比（引用 Cursor Rules / Cline / Copilot / llms.txt 的做法）
- 给出分步修复方案，点名具体文件和修改内容
输出约束：单个维度不超过 1000 字。
五维诊断体系
一、信号效率
加载到 AI 上下文的每一行，是否都对生成质量有直接贡献？
检查点：
- 分层结构：是否有清晰的 Core / Patterns / Context 分层，还是所有内容堆在一个文件里？
- 信号密度：是否存在大段"教育性"内容（解释性注释、背景说明、设计哲学）？AI 不需要被教育，它需要被指令。
- 按需加载：是否有条件加载机制（按文件类型/模块/阶段触发），还是一次性全量灌入？
- 信息去重：同一规则是否在多处重复定义？
- 动态管理：API 清单、组件清单等高频变化内容是自动生成还是手动维护？
典型病灶：
- 一个 2000 行的 .cursorrules，其中 40% 是注释和解释
- 同一命名规范在 3 个文件中重复出现
- 写一个简单组件也要加载全部架构文档
对标参考：Cursor Rules 200 行精简原则 | Cline YAML frontmatter 条件加载 | llms.txt Optional 分区 | Anthropic Context Engineering 信号密度最大化
二、指令可靠性
换一个更弱的模型，核心指令还能被正确执行吗？
检查点：
- 具体性：指令是否具体可执行（"使用 camelCase 命名"），还是模糊抽象（"使用好的命名"）？
- 规则化：关键决策是否用 if-then 规则表达，而非依赖 AI "理解"上下文后自行判断？
- 正反示例：是否提供正确和错误写法的对照？
- Why 解释：规则是否附带简短理由？（帮助模型在边缘 case 做正确推断，但不能代替规则本身）
- 降级策略：弱模型无法完成任务时，是否有明确的 fallback（人工介入点、简化模式）？
- 推理步数：每条指令被正确执行需要几步推理？超过 2 步的指令对弱模型不可靠。
典型病灶：
- 使用隐喻或需要文化背景的描述（"像写诗一样优雅"）
- 复杂嵌套条件需要 3 步以上推理
- 没有降级方案，弱模型失败时只能重试
对标参考：Anthropic Prompting Best Practices "具体优于抽象" | llms.txt 规则化指令模式 | 显式声明模式
三、安全护栏
AI 犯错时，最坏后果是什么？有没有自动拦截？
检查点：
- 行为边界：是否定义了「可做 / 需确认 / 禁止」三级行为边界？
- 自动化检查：ESLint / TypeScript strict / Prettier 等自动化护栏是否覆盖核心规范？
- 范围限定：是否有输出锁、单次修改文件数上限等范围限制？
- 错误闭环：是否有 错误检测 → 自动修复 → 再验证 的完整闭环？还是只有检测没有修复？
- 高危保护：删除操作、全局配置修改、数据库操作等高危行为是否有额外拦截？
- 纠错沉淀：错误经验是否转化为规范永久记录，防止复现？
典型病灶：
- AI 可以不经确认直接删除文件
- 没有 TypeScript strict 模式，类型错误运行时才暴露
- 错误被检测但无自动修复，人工兜底成本高
对标参考：OWASP AI Security Guidelines | Galileo 质量框架 | ESLint 护栏模式
四、变更韧性
改一个需求，要动多少文件？回退成本多高？
检查点：
- 影响半径：修改一个字段/接口，需要改动多少文件？可控标准：≤3 个。
- 分阶段交付：是否支持 PRD → Demo → 接口对接 → 联调 的渐进式流程？
- 上下文恢复：中途打断后能否快速恢复？是否有快照/摘要机制？
- Mock 共存：Mock 数据和真实接口能否共存并无缝切换？
- 版本回退：是否有版本管理 + 回退路径？
- 增量修复：AI 出错时，多大比例的问题可以增量修复而非推倒重来？
典型病灶：
- 改一个表单字段需要同时修改 type 定义、API 层、组件、Mock 等 6+ 个文件
- 做到一半被插入紧急需求，切回来时完全丢失上下文
- 没有 Mock 机制，接口没到齐前无法开发
对标参考：Strangler Fig Pattern | ADR 架构决策记录 | 生命周期回溯机制
五、上手成本
一个新人（或一个新工具）接入需要多少步？
检查点：
- 入口清晰度：是否有唯一明确的入口文件？新人知道从哪开始？
- 认知负荷：入口文件是否在 200 行 / ~3000 Token 以内？
- 快速路径：是否有 CRUD / 表单 / 列表等常见场景的快速模板？
- 错误反馈：错误信息是否具体可操作（"缺少 X 字段"），还是模糊（"请检查配置"）？
- 跨工具兼容：规范格式能否同时适配 Cursor / Cline / Copilot / Qoder 等多种工具？
- 标准协议：是否遵循 llms.txt / MCP / AGENTS.md 等通用标准？
典型病灶：
- 新人需要读 10+ 个文件才能开始第一个任务
- 入口文件 500+ 行，认知负荷过重
- 规范格式只适配一种工具，换工具要重写
对标参考：DX 三维模型 | 认知负荷理论 | MCP 协议 | AGENTS.md 规范
三个诊断视角
评估时从以下三个视角交叉验证。不是机械"切换角色"，而是用不同的提问角度探查盲区：
| 视角 | 核心追问 | 验证方法 |
|---|
| 弱模型代言人 | "用 4K 窗口的轻量模型能跑通核心流程吗？" | 只看核心规范（去掉 optional），估算 Token 量，检查每条指令推理步数是否 ≤ 2 |
| 混沌工程师 | "如果 AI 忽略了这条规则，最坏会怎样？" | 对每条关键规则做失效分析：后果严重但没有自动拦截 = 高风险缺口 |
| 新人 | "第一天上手，要读几个文件、几步能跑通？" | 模拟从零路径：入口在哪 → 读什么 → 做什么 → 多少步完成第一个任务 |
成熟度定位（非评分）
不打分，仅定位当前阶段，辅助确定改进方向：
| 阶段 | 关键标志 |
|---|
| 探索期 | 无统一入口文件；团队成员各用各的提示方式；AI 生成代码经常需要大幅修改 |
| 体系期 | 有统一入口 + 分层结构；自动化检查覆盖主要规范；有条件加载机制；新人 onboarding 有路径 |
| 自适应期 | 规范版本化管理；多模型兼容验证通过；错误 → 沉淀 → 防复现闭环运转；跨工具可迁移 |
输出规则
- 快速扫描输出不超过 500 字，必须包含：每个维度一行判定 + 最关键 1-2 个改进建议
- 深潜分析针对单个维度展开，不超过 1000 字
- 每条结论必须引用具体文件路径和内容作为证据
- 不做数值打分，不输出评分表格
- 如果架构确实好，说明具体好在哪、哪些业界方案采用了类似设计
- 改进建议必须可执行："在 X 文件中把 Y 改为 Z"，而非"建议提高信号密度"
- 发现以下隐藏问题时主动标记：
- 隐式约定：未明文规定但 AI "应该知道"的规则
- 循环依赖：A 引用 B，B 引用 A
- 僵尸规范：已废弃但仍存在的规则
版本历史
| 版本 | 日期 | 变更 |
|---|
| v2.0 | 2026-04-22 | 重构：9 维 → 5 维诊断体系，删除数值评分改为证据驱动诊断，11 角色 → 3 视角，删除报告模板，增加快速扫描/深潜双模式 |
| v1.0 | 2026-04-04 | 初始版本，九维评估体系、五级成熟度模型、多角色视角矩阵 |
