我怎样用文档驱动一个全栈项目

为什么个人全栈项目也需要文档

很多人会觉得文档是团队协作才需要的东西，个人项目代码能跑就够了。但栖光这种项目不太一样。它包含微信小程序、后端 API、React 后台、MySQL、Redis、OSS、OpenAPI 类型生成、数据看板、支付退款、优惠券、地址簿、积分和存酒等业务模块。

这类项目如果只靠记忆维护，很快会遇到问题：订单状态为什么要分支付状态和履约状态？地址为什么要做订单快照？数据看板为什么要拆经营口径和资金口径？员工账号为什么只限制敏感操作而不做复杂岗位权限？这些问题单看代码很难马上恢复上下文。

所以我在栖光里把文档当成项目的一部分，而不是结束后的装饰。代码回答“怎么实现”，文档回答“为什么这样实现”“这次改动影响什么”“怎么确认它可靠”。

栖光的 docs 目录承担了不同职责

栖光的 docs/ 不是一份 README 解决所有问题，而是按项目运行需要拆成多个入口。

project-overview.md 说明项目名称、目标、MVP 范围、非目标范围和成功标准。它让后续所有人先知道，栖光是酒吧/餐饮场景里的小程序点餐与商城系统，不是泛泛的商城模板。

product-requirements.md 记录顾客、运营人员和开发维护人员的需求，也记录 V1.2、积分、存酒、员工账号、后台权限规则等后续补充。它告诉我功能为什么存在，以及哪些东西当前不做。

architecture.md 记录三端边界、核心实体、接口契约和关键决策。比如后端使用 Express + tsoa，Admin 使用 React、Vite、Ant Design，小程序遵守微信运行环境限制，数据库结构以 backend/init.sql 为权威来源。

task-board.md 记录任务状态、版本进度、长期任务和每次重要变更。它不仅记录“做完了什么”，还记录并行性、风险、写入范围和完成定义。

test-strategy.md 则记录自动化验证、人工验收、测试缺口和发布门槛。对于支付、退款、看板口径和小程序兼容性这类风险点，测试策略比口头说“测过了”可靠得多。

docs/ 目录结构截图，展示项目文档按智能体协作、决策记录、发布记录、SQL、测试、工作流和核心说明文件分层维护。

一次改动怎样穿过文档链路

以 2026-07-02 的后台数据看板收款口径重构为例，这次改动不是只改一个 Dashboard 页面。

问题最初来自业务口径：经营成交额、净营业额、微信实收、余额支付、充值入账和退款影响不能继续混在一个“营业额”里。这个判断需要进入架构文档，说明看板聚合如何区分经营指标和资金指标。

任务看板里记录了这次变更的输出：后台看板聚合接口新增经营/资金指标、双趋势和最近营业订单/充值/退款；Admin 看板页面重构为经营概览、资金概览、趋势分析和分组最近订单。

测试策略里记录了验证链路：后端 config.service.test.ts、后端构建、Admin generate-api、Dashboard 页面契约测试、类型检查和构建，以及真实后台数据的人工验收项。

这就是文档驱动的意义：一次变更不只留下代码 diff，还留下需求原因、架构解释、任务记录、测试证据和剩余风险。

文档让 AI 辅助开发更可靠

栖光这种项目如果交给 AI 辅助开发，文档更重要。

如果只对 AI 说“帮我改一下营业额统计”，它很可能只会改某个 SQL 或页面字段。但如果上下文里明确写着经营口径、资金口径、订单时间、退款处理时间、OpenAPI 生成链路和测试要求，AI 才更容易沿着项目事实做事。

文档不是用来限制创造力的，而是用来限制误解的。它告诉参与开发的人或工具：这个项目的边界是什么，已有约定是什么，不能随意改什么，改完要同步哪些地方。

这对单人项目尤其有价值。因为“未来的我”其实就是另一个协作者。几周后再回到项目里，如果没有文档，我也需要重新考古；如果文档持续更新，我可以很快回到正确上下文。

文档驱动不是把一切写满

我不认为文档驱动等于写一堆没人看的文档。栖光里的文档有一个很明确的原则：只记录会影响后续判断的信息。

需求文档记录范围、验收标准和待确认问题；架构文档记录边界、状态模型、接口契约和风险；任务看板记录版本、任务状态、影响范围和验证；测试策略记录自动化、人工验收和剩余风险；发布记录记录数据库变更、配置变更和发布前重点回归。

这些内容不是为了好看，而是为了减少下一次修改的成本。一个真实业务项目最怕的不是没有功能，而是每次改动都要重新猜系统为什么这么设计。

这件事证明了什么能力

对外展示栖光时，我不想只说“我做了小程序、后台和后端”。更重要的是，它能说明我知道一个业务系统怎么被持续维护。

文档驱动证明的是交付意识：功能做完后，能不能说明改了什么、为什么改、影响哪些端、怎么验证、还剩什么风险。它也证明维护意识：项目不是一次性作品，而是可以继续迭代、交接和复盘的系统。

这比单独展示几个页面更有说服力。因为真实项目最后拼的不是谁页面多，而是谁能把需求、代码、接口、测试和发布组织成一条可追踪的链路。