方案实施原则

本文约定：AI（及协作者）在执行用户需求时，应如何理解、选型与落地。
适用于本仓库 / 个人 Wiki 及相关开发协作。
不限于某一功能（如端口、布局、渲染等）；所有需求默认遵循本文。

1. 核心原则（按优先级）

1.1 需求第一

• 先准确理解用户要什么、成功标准是什么、明确不做什么。
• 不得在未说明的情况下，用「行业标准」「框架习惯」「更优雅」等理由，擅自削弱、替换或取消用户已确认的需求。
• 仅当需求存在明显矛盾、安全风险、不可维护或成本与收益严重失衡时，才提出调整建议；默认先按需求落地。

1.2 同需求下，现成方案优先

针对用户已经提出的同一需求，实现时应：

1. 先检索：官方文档 / 成熟开源库 / 主流脚手架与社区常见做法；
2. 尽量直接使用或薄封装现成能力；
3. 避免从零造轮子（重复实现已有成熟方案已覆盖的能力）。

「自研」在这里的正确含义是：

• 自己定义产品规则与组装方式；
• 底层尽量用开源与成熟工具；
• 不是一切从零手写。

1.3 行业标准 = 参考怎么做，不是否定要做什么

有成熟方案能满足需求 → 用成熟方案。
成熟方案盖不全、但需求仍成立 → 允许最小必要自写，并说明现成方案差在哪里。

1.4 需求不合理时才反馈

反馈的条件应是需求本身有问题，而不是「实现稍微麻烦」或「和某框架默认不一致」。

2. AI 执行用户需求的默认工作流

对任意用户需求（功能、改 bug、重构、文档、配置等），默认按序执行：

1. 确认需求
   - 做什么 / 不做什么
   - 成功标准（如何算完成）
   - 边界与约束（环境、兼容、安全等）

2. 检索成熟方案
   - 官方能力是否已支持
   - 有无主流库 / 工具 / 公认模式
   - 同需求下常见实现是什么

3. 选型落地
   - 能直接用 → 直接用
   - 差一点 → 配置或薄封装现成方案
   - 现成无法满足 → 最小自写，并简要说明原因

4. 实现与验证
   - 按选定方案实现
   - 按成功标准自检（能跑通、能复现用户场景）

5. 说明（必要时）
   - 用了什么现成方案
   - 若有自写，为何现成不够
   - 如何使用 / 如何验证

6. 仅当需求本身有问题时
   - 再与用户反馈，提出可选调整
   - 不擅自用「标准答案」替换用户目标

3. 「自研」允许与禁止（通用）

4. 对 AI 的明确要求（清单）

1. 先对齐需求，再谈实现与标准。
2. 选型前先找现成方案；需要时说明选用了什么、为何。
3. 禁止未说明就用「行业标准」替换用户已确认的行为。
4. 自写前先自问：是否已有库/官方选项？差在哪？能否薄封装？
5. 在不损害需求的前提下，命名、目录、命令等尽量对齐常见工程习惯，便于维护。
6. 文档与代码一致：重要约定写进仓库（如本文、docs/、配置注释），避免只存在于对话里。
7. 大改动前，若存在多种成熟路线，可简要对比后推荐，但以用户最终选择的需求为准。

5. 反面示例与正面示例（通用，非绑定某一功能）

反面（错误）

• 用户要 A 行为 → AI 认为「标准只做 B」→ 只做了 B，且不说明。
• 未检索是否有成熟库 → 直接从零实现一整套。
• 用「更专业」「更优雅」静默改变产品行为。

正面（正确）

• 用户要 A → 检索到库 X / 官方选项 Y 能覆盖 → 使用 X/Y 落地 A。
• 用户要 A → 现成方案只能覆盖 A 的一部分 → 用现成方案 + 最小补全，并说明缺口。
• 用户要 A → A 本身有安全/逻辑问题 → 先反馈，再等用户决定是否改需求。

6. 一句话（贴在协作约定里）

需求第一。
同一需求下，优先成熟、现成的方案，尽量直接用，少造轮子。
行业标准用来参考「别人怎么实现」，不是用来否定「用户要什么」。
只有需求不合理时才反馈；现成不够时再最小自写，并说明原因。

7. 修订

本文位于 content/AI/，作为本站可浏览的协作规范；工程侧也可在 docs/ 引用本文链接。