基于文档的 Vibe Coding：README 与 docs 的分工

摘要

文章分享了作者与 AI 协作编程半年的实践经验，核心观点是：对话噪音多、AI 易顾此失彼，而文档能成为与 AI 共享的稳定语境。作者提出将 README 定位为项目入口索引，docs 定位为内部知识库，通过状态标记和生命周期管理，让沉淀性文档与过程性文档各司其职，实现代码与文档同源演进。

内容框架与概述

文章开篇指出 Vibe Coding 的本质是"用文档与 AI 协作"。由于 AI 受上下文限制，对话中的修改容易顾此失彼，而文档可以作为相对稳定的共享语境，帮助从模糊想法逐步推进到清晰方案。作者强调需要区分沉淀性文档和过程性文档，避免"都是重点就没有重点"的困境。

随后，作者详细阐述了 README 与 docs 的分工设计。README 作为仓库门面，承担整体介绍、环境配置、目录导航等职责；docs 作为内部知识库，按 scope（愿景原则）、specs（固化定论）、staging（过渡方案）、bugs（问题记录）四个子目录组织内容。

文章最后介绍了文档命名规范和生命周期管理机制。通过 [open]、[solved]、[abandoned] 三种状态标记，清晰追踪每份文档的进展，确保过渡区文档最终要么固化进 specs，要么被明确废弃，形成闭环管理。

核心概念及解读

Vibe Coding：指与 AI 自然协作的编程方式，作者将其还原为"用文档与 AI 协作"这一朴素实践，强调文档是减少对话噪音、建立稳定语境的关键载体。

沉淀性文档与过程性文档：前者如 specs 中的固化定论，是已确定的知识；后者如 staging 中的执行方案，是仍在推进的内容。区分二者能避免信息混杂，让重点真正成为重点。

README 与 docs 分工：README 是索引和规则，回答"有什么、怎么用"；docs 是内容和知识，存放具体的需求、方案和决策记录。二者配合实现代码与文档同源演进。

状态标记与生命周期：通过 [open]、[solved]、[abandoned] 三种状态标注文档进展，配合从 staging 到 specs 的流转机制，确保每份文档都有明确归宿，不留模糊地带。

原文信息

此摘要卡片由 AI 自动生成