#006-规模化实践:从个人项目到团队协作

当文档驱动遇到复杂系统 + 博客 v0.8 复杂化演化

在前几篇文章中,我们像搭积木一样,从零开始搭建了一个功能完备的个人博客。有了搜索,有了分类,它看起来已经是一个合格的 v0.5 版本了。

但是,如果你的野心不止于此呢?

如果这个博客不是你一个人写,而是一个团队的技术专栏?如果流量暴涨,需要极致的 SEO 和性能优化?如果你想把内容推向全球,需要支持多语言?

这时候,你会发现我们之前的那个单一的 spec.md 文件开始变得臃肿不堪。它像是一个塞满了杂物的储物间,AI 读起来费劲,你改起来也头疼。

欢迎来到**规模化(Scaling)**的世界。在这一篇,我们要把这个"舒适的小木屋"升级成一座"现代化的大厦"。

规模化的三个维度

当我们谈论"把项目做大"时,通常不仅仅是指代码行数的增加。在文档驱动开发的语境下,规模化体现在三个维度:

代码规模:从几百行简单的逻辑,变成包含复杂状态管理、数据流转的庞大系统。
团队规模:从"我一人吃饱全家不饿"的单兵作战,变成需要前后端配合、产品研发协同的多人舞蹈。即使你现在是独立开发者,"现在的你"和"一个月后的你"其实也是一种团队协作。
功能复杂度:从单纯的静态展示,变成需要处理权限、国际化、高性能渲染的动态应用。

面对这些挑战,如果还抱着那三个简单的 Markdown 文件不放,就有点像拿着水果刀去砍大树了。我们需要升级我们的兵器库。

博客 v0.8:不仅仅是功能的堆砌

为了演示这种变化,我们给博客定下了 v0.8 的演化目标。这次不只是加个按钮那么简单,我们要引入系统级的复杂度:

多作者系统:不再只有"站长"一个人,我们需要支持多位作者,每位作者有自己的头像、简介和专栏页。
SEO 极致优化:自动生成 sitemap,支持 Open Graph 协议,让分享到 Twitter/微信时的卡片美观大方。
性能与国际化:引入图片自动优化,并支持中英文一键切换。

策略一:文档的模块化重构

在 v0.5 之前,我们的 spec.md 可能只有 200 行,AI 一眼就能读完。但加上上面这些功能,它可能会膨胀到 2000 行。

AI 的注意力是有限的(Context Window),人类的注意力更是如此。

解决办法简单而粗暴:拆。

我们不再维护单一的 spec.md 和 plan.md,而是将它们变成文件夹:

intent.md:依然保持独立。因为无论项目多大,核心愿景和价值观应该是稳定且唯一的。
spec/ 文件夹:
- core-features.md:核心功能(文章列表、详情)。
- author-system.md:专门描述多作者系统的逻辑。
- seo.md:专门定义 SEO 的元数据规范。
- i18n.md:国际化文案和路由规则。
plan/ 文件夹:
- architecture.md:整体技术架构。
- data-model.md:统一的数据结构定义。
- performance.md:性能优化策略。

这样做的最大好处是关注点分离。当你让 AI "帮我优化作者页面的样式"时,你只需要给它 spec/author-system.md,而不需要塞给它无关的 SEO 规则。

策略二:团队协作中的文档流转

如果这个项目是你和朋友一起做的,文档驱动的威力会倍增。

在传统的团队里,产品经理写完需求文档(Word/Wiki)就扔给开发,开发写代码时发现文档有漏洞,往往直接在代码里"修补",导致文档和代码迅速脱节。

在文档驱动的团队里,我们遵循这样的工作流:

文档即代码:所有的 .md 文件都和代码在同一个 Git 仓库里。
变更前置:如果你想改一个功能,必须先提交一个修改 spec/*.md 的 Pull Request (PR)。
Code Review 升级:大家先 Review 文档的变更。如果文档逻辑通了,再动手写代码(或者让 AI 写代码)。

遇到分歧怎么办?

如果是代码实现有分歧(比如用哪个库),回溯到 plan 层讨论。
如果是功能逻辑有分歧(比如要不要做点赞功能),回溯到 spec 层讨论。
如果是方向性分歧(比如我们要不要做付费墙),回溯到 intent 层——这符合我们的初衷吗?

这种层级分明的"冲突解决机制",能避免无休止的扯皮。

策略三:上下文工程 (Context Engineering)

随着文档被拆分,一个新的问题出现了:如何让 AI 理解全貌?

这就涉及到了上下文工程。简单说,就是你需要根据当前的任务,动态地喂给 AI 它需要的"营养"。

如果我要开发"多作者系统",我不仅需要提供 spec/author-system.md,还需要提供 plan/data-model.md(因为它定义了作者的数据结构),甚至可能需要 plan/architecture.md(确认文件存在哪)。

如果你使用的是 Cursor 这样的现代编辑器,你可以利用 @Files 功能精准投喂。如果是自动化脚本,你甚至可以编写一个简单的索引文件 index.md,告诉 AI:"如果你要改 A 功能,请阅读文件 X 和 Y。"

这就像是给 AI 准备了一个导航地图,让它在文档迷宫中不会迷路。

v0.8 实战:让复杂变得可控

让我们看看运用这套方法论,博客 v0.8 是如何诞生的。

1. SEO 优化我们在 spec/seo.md 中定义了:"每个页面必须包含 canonical URL"。然后在 plan/architecture.md 中规定了使用 next-sitemap 插件。AI 读取这两份文档后,不仅生成了配置代码,还自动去检查了现有的页面组件,补全了缺失的 Head 标签。

2. 性能优化我们在 plan/performance.md 中写下了严苛的指标:"Lighthouse 评分不能低于 95"。AI 建议并实施了 next/image 的全站替换,并配置了路由预加载。因为它清楚地知道,这是 Plan 中的硬性约束。

3. 最终成果当你打开 v0.8 的博客,点击一位作者的头像,流畅地跳转到他的专栏, URL 是友好的,图片是瞬间加载的,而且可以随时切换成英文版。

这一切的背后,不是一堆乱如麻的代码,而是井井有条的 docs/ 文件夹。

顺手的兵器:工具推荐

工欲善其事,必先利其器。在规模化实践中,有几个工具能帮你事半功倍:

Obsidian:不仅是笔记软件,更是最好的本地文档管理工具。它的双向链接功能可以帮你构建文档之间的引用关系。
Next.js (App Router):之所以一直推荐 Next.js,是因为它的文件路由结构天然契合文档的结构化思维。
AI 辅助工具:除了 Cursor,你还可以尝试编写简单的脚本,利用 CI/CD 在提交代码时自动检查文档是否更新(比如检查最近修改的代码文件对应的 spec 文件是否在同一次 commit 中变更)。

结语

从 v0.1 到 v0.8,我们见证了文档驱动开发如何从"写个小纸条"演变成"绘制工程蓝图"。

规模化并不可怕,可怕的是用管理小作坊的方式去管理大工厂。通过模块化文档、清晰的协作流程和精细的上下文工程,我们让 AI 即使面对复杂的系统,也能保持清醒和高效。

现在的博客已经接近生产就绪(Production Ready)了。但是,在这条路上跑了这么久,我们是否也应该停下来反思一下?

文档驱动真的是万能的吗?什么时候我们应该毫不犹豫地抛弃文档,直接写代码?这套方法论的边界在哪里?

下一篇,我们将进行一次深刻的反思与复盘,探讨文档驱动开发的局限性与"防走火"指南。