AI Coding 项目怎么拆：从微信公众号 Markdown 组件需求到 9 阶段开发计划

很多 AI Coding 项目不是输在模型不会写代码，而是从一句模糊需求直接跳到了实现：功能边界不断扩张、技术方案彼此冲突、一次改动覆盖多个模块，最后没人能判断“是否完成”。本文以 md-wx 的现有规划材料为例，整理一套可复用的 需求—架构—任务—规则—验收 方法。项目当前只有规划文档，没有 package.json 与源码，因此本文讨论的是设计方法，运行未验证。

1. 先把一句想法改写成可验收产品

md-wx 最初要解决的问题可以概括为：把 Markdown 内容更低成本地发布到微信公众号。

但这句话还不能直接开发。需求文档进一步把产品限定为一个通用 NPM 组件，形成了清晰的数据链路：

外部 Markdown
  → 实时预览
  → 切换主题、代码样式和设备视图
  → 复制当前排版结果
  → 粘贴到微信公众号编辑器

目标用户也被限制为三类：内容创作者、排版或写作工具开发者，以及需要嵌入预览和复制能力的团队。

更重要的是，文档明确列出本期不做的内容：Markdown 编辑器、用户账号与团队协作、草稿和云同步、自动发布、图片素材管理、AI 写作等。这个“不做清单”能防止 AI 因为看到相关场景就自动扩展功能。

可复用的需求检查表

维度	必须回答的问题	md-wx 的答案
输入	系统接收什么	外部 Markdown 文本
输出	用户最终得到什么	实时预览与可粘贴内容
状态	哪些设置需要保持	主题、设备模式、设置区显隐
边界	本期明确不做什么	编辑、账号、云同步、自动发布等
验收	如何判断完成	结构正确、状态保持、复制反馈、微信粘贴检查

2. 技术选型必须连成一条实现链路

项目规划使用 React 18+、Vite、CSS Modules 与 PostCSS。Markdown 由 react-markdown 配合 remark-gfm 解析；代码块由 react-syntax-highlighter 渲染，默认采用 github-dark；复制阶段计划用 juice 将 CSS 转为内联样式。

这些技术不是一张依赖清单，而是分别解决链路中的具体问题：

1. React 接收 Markdown 与主题、设备等状态。
2. react-markdown + remark-gfm 把文本转成可定制的 React 元素。
3. 自定义 CodeBlock 接管 fenced code，保留缩进并添加 macOS 三色装饰点。
4. CSS Modules 隔离组件内部样式，主题文件负责预览外观。
5. 复制时取得预览 HTML，再由 juice 将主题规则写入元素的 style。
6. 处理结果写入剪贴板，交给微信公众号编辑器。

组件边界也随之变得自然：Previewer 负责渲染，SettingsPanel 负责交互，CodeBlock 负责高亮；useTheme、useViewMode 和 useCopyToClipboard 承载可复用逻辑。

一个必须验证的技术风险

现有架构文档计划调用 navigator.clipboard.writeText 复制 HTML 字符串。但“字符串里含有 HTML 标签”不等于“剪贴板中存在富文本 HTML”。目标编辑器可能把它当纯文本处理。

因此，复制任务不能只验收“API 调用成功”，还要验证：

• 剪贴板是否同时提供 text/html 与 text/plain；
• 标题、列表、表格、代码块是否保留结构；
• 五套主题的内联样式是否被微信编辑器接受；
• 失败时是否有明确反馈；
• 空内容是否禁止复制。

具体 API 与微信编辑器行为需在实现阶段测试，当前运行未验证。

3. 用可见结果拆出 9 个开发阶段

任务拆分文档没有要求 AI 一次生成整个组件，而是按可观察结果组织为九个阶段：

1. 项目基础架构；
2. Markdown 核心预览；
3. 主题系统；
4. 代码块增强；
5. 响应式与视图模式；
6. 复制和微信样式兼容；
7. 组件 API 与导出；
8. 本地开发与联调；
9. NPM 打包与发布。

这样的顺序体现了依赖关系。没有可运行的基础工程，就不能验证渲染；没有稳定预览，就不应先做复制；没有明确公共 API，就无法可靠测试 NPM 包的宿主集成。

每个任务又包含四个元素：优先级、具体范围、预期效果和验收标准。例如“Markdown 渲染引擎”不只是安装依赖，还要求创建 Previewer、支持常用语法和 GFM、实现实时更新，并通过语法正确性与更新行为验收。

推荐的任务模板

### 任务 X.X：任务名称

- 目标：完成后用户能看到什么？
- 范围：本任务允许修改哪些模块？
- 依赖：开始前必须完成什么？
- 实现项：3～6 个具体动作。
- 验收：可操作、可观察的结果。
- 非目标：本任务明确不处理什么。
- 停止点：验收后等待确认，不自动进入下一任务。

模板的价值不是形式整齐，而是让 AI 知道从哪里开始、在哪里停止，也让用户能在小范围内审查结果。

4. 用项目规则限制 AI 的自由发挥

需求和任务告诉 AI “做什么”，项目规则则规定“只能怎么做”。md-wx 的规则包括：

• 使用 React 18+ Hooks、Vite、CSS Modules + PostCSS；
• Markdown 解析、高亮和内联样式使用指定依赖；
• 组件、函数和 CSS 类遵守统一命名；
• React 与 React DOM 作为 peerDependencies 和 devDependencies，并从库构建中 external；
• 每次只执行一个明确任务；
• 完成后按任务验收标准自检，并等待用户确认。

其中最后三条特别重要。组件库若把 React 打进产物，可能与宿主应用产生重复实例；AI 若跨任务“顺手优化”，则会扩大审查面；没有明确停止点，任务拆分就只停留在文档里。

可以把项目规则理解为一组不变量：任何代码改动都不能破坏它们。规则越能自动检查越好，例如 ESLint、Prettier、构建脚本和发布字段都比自然语言提醒更稳定。

5. 开工前先处理 3 个规格冲突

文档足够详细，不代表可以直接编码。横向核对后，当前至少有三个问题需要先统一。

5.1 五个主题名称不一致

需求文档使用“经典简约、商务蓝、翡翠绿、暖阳橙、墨韵雅致”；设计指南则使用“极简白、樱花粉、森林绿、海洋蓝、日落橙”。

这会影响主题常量、CSS 文件名、UI 文案与验收用例。建议以产品需求为基线，再同步设计 token，而不是让实现阶段自行猜测。

5.2 任务文档路径不一致

项目规则要求依据 docs/task_breakdown.md 执行，但仓库中的实际文件是 docs/task.md。如果不修正，AI 在执行规则时无法定位权威任务边界。

5.3 剪贴板方案与目标可能不匹配

架构给出了 CSS 内联思路，但写入剪贴板的格式仍需验证。应在复制阶段把 MIME 类型和微信编辑器粘贴结果加入验收，而不是只测试复制按钮是否提示成功。

6. 一套可复用的 AI Coding 工作流

将 md-wx 的方法抽象后，可以得到以下流程：

第一步：需求收敛

• 写清目标用户、输入、输出和核心状态；
• 单独列出本期范围与非目标；
• 为每个核心场景提供可操作验收标准。

第二步：架构映射

• 从关键数据流反推技术选型；
• 每个依赖都要对应一个明确问题；
• 定义组件职责和共享状态边界；
• 把外部系统兼容性列为验证项。

第三步：任务分层

• 先基础能力，后增强能力；
• 每个任务只产生一个主要可见结果；
• 写明依赖、范围、非目标和停止点；
• 验收失败时只修当前任务。

第四步：规则固化

• 固定技术栈、目录、命名和依赖策略；
• 规定 AI 每次只执行一个任务；
• 尽量将规则转为 lint、format、build 等自动检查。

第五步：一致性审查

• 对照需求、设计、任务和规则中的同一概念；
• 发现命名、路径、默认值冲突时先统一；
• 对未运行的能力明确标注“未验证”。

7. 最终自检清单

在让 AI 写第一行代码前，可以逐项检查：

• 产品输入、输出、状态和非目标是否明确？
• 每项技术是否能映射到一段数据流？
• 组件职责是否单一，共享状态是否只有一个事实来源？
• 任务是否包含范围、依赖、验收和停止点？
• 项目规则引用的路径是否真实存在？
• 需求、设计和任务中的名称与默认值是否一致？
• 外部系统兼容性是否安排了真实环境验收？
• 文档规划与已实现结果是否明确区分？

结语

AI Coding 的可控性并不来自一句“请严格按要求实现”，而来自一套能相互校验的工程结构：需求限制边界，架构连接数据流，任务缩小上下文，规则约束执行方式，验收定义停止条件。

md-wx 目前最有价值的成果不是代码，而是已经形成了这条管理链路。下一步不应直接冲向完整组件，而应先关闭三个规格冲突，再只执行“项目初始化和配置”这一个任务，用真实构建结果完成第一次验收闭环。

标签：AI Coding, React, Markdown, NPM组件, 软件工程