当文档驱动遇到复杂系统 + 博客 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 写代码)。
遇到分歧怎么办?