跳到正文

目录

微信原文

Vibe Coding 中的项目上下文管理

Felix2026-10-18约 4 分钟人机协作
最近在开发个人网站的过程中，我慢慢意识到，需要从项目的角度管理文件，尤其是 AGENTS.md、DESIGN.md 和 PROJECT_MAP.md 这类文件，需要持续维护。
因此，我想分享一下，我是如何构建和优化这几个文件的，以及如何通过两个 Repository，把公开代码和私密资料分开。

0x01 背景

建站这个事情持续了非常久，之前的文章里也介绍过，可能从 21 年就开始了。后来进入 AI 的时代，25 年我也尝试过用 Claude 4 这些模型去开发，对当时模型的能力也有一些感受。
慢慢长路之网站搭建
到了 26 年目前这个阶段，模型的智能已经大幅度提升。但我不是前端开发，对前端这些基本不了解。我只知道如何用自然语言描述自己的想法，然后探索怎么给它传递清晰的指令。
目前开发下来，有几点能明显感觉到进步：
  1. 有了 DESIGN.md，可以把整体的视觉设计固定下来。
  1. 现在的测试流程已经比较完整。基本上每次新的需求开发完，都能运行起来，不像以前经常出错。虽然最后的结果可能跟预期不太一样，但已经形成了一个闭环。
  1. AGENTS.md 和 PROJECT_MAP.md 在项目中起到了向导的作用，尤其是在 Agent 修改项目、增加功能的时候。这也是这一次重点想讲的内容。

0x02 问题

为什么要构建这几个文档？主要有两个原因。
  1. 项目不断修改，获取上下文的消耗越来越大。
      2. 我发现，随着项目不断修改，Agent 运行得越来越慢。有时候新建一个窗口，它会消耗大量的 Token，去获取项目的上下文。
      所以，我认为有必要再学习一下如何管理上下文，也因此开始了解 AGENTS.md 这类文档的用法。
  1. 切换 IDE 和模型，需要重新交接项目信息。
      2. 我最近也在寻找免费的 Token 活动。很多平台会把活动绑定到自己的 IDE 上，所以我需要切换不同的 IDE，去开发同一个项目。
      这也让我开始关注，如何让不同的 AI 快速了解我的项目。
换了一个 IDE，或者新开一个窗口之后，我该如何让新的 Agent 了解项目的历史？我先后考虑了两种方式：
  1. 通过 Git 分支上的 Commit。
      2. 但上面通常只是一些简单的描述，不足以让新的 Agent 了解整个项目的历史。
  1. 让上一个 Agent 写一份 Handover 文档。
      2. 把项目的情况交接下来，再由新的 Agent 接着使用。
而这次的整理，就是把原来集中在 Handover 文档里的内容拆开，分别放进 AGENTS.md、PROJECT_MAP.md、DESIGN.md 等文件，让它们各自负责不同的事情。

0x03 文档整理

这几个文件的分工，可以简单理解为：
  1. AGENTS.md：负责全局的 AI 协作规则。
  1. PROJECT_MAP.md：负责资料索引和任务路由。
  1. DESIGN.md：负责固定整体的视觉设计。
不同 IDE 的规则文件，再作为指向这些文档的入口。
将之前的handover文件拆分成标准的传递文档
将之前的handover文件拆分成标准的传递文档
整理之后，目录结构是这样的：
notion image
这样，不管换哪个 IDE、哪个模型，都有一套可以继续维护和传递的项目文档。

0x04 公私分离

完成了这几个文件的梳理之后，我突然又想到一个问题。
我使用的是 NotionNext 的 Fork，目前这个仓库是公开的。平时整理的设计理念、品牌图标等相关资料，都会放在这些文件或者项目目录里。也就是说，这些东西一直包含在我的公开仓库中。
所以，我就在考虑，怎么能把它们剔除出来。
经过和 ChatGPT 聊了一些方案之后，发现分离出来是可行的，具体分成两部分。
  1. 把代码和私密资料分开存放。
      2. 在一个大文件夹下，放一个公有库、一个私有库。公有库保留项目代码，私有库就存放这些品牌设计相关的资料。
  1. 通过 AGENTS.md 保留读取指引。
      2. 在项目转移的时候，或者换一个 IDE 调用的时候，怎么引用这些资料呢？
      就是通过项目中的 AGENTS.md 文件来定义，将 Agent 的寻址重新导向到我的私有库文件夹中。
这样，品牌设计相关的资料不用继续放在公开仓库里，Agent 又可以按照 AGENTS.md 中的指引去读取。这种方式，就解决了我这次想把两者分开的需求。
完成分割
完成分割

0x05 使用情况

以上这些步骤，都可以让 AI 帮忙完成。我也是通过 Gemini 来帮我梳理这些文档，最后都落地了。
目前用下来，有两点感受：
  1. 在不同 AI 之间切换的过程中，没有遇到什么阻碍。
  1. 在一个模块设计完之后，都能把相关的经验再次沉淀到这些文档里。
所以我认为，如果要构建一个长期使用的项目，梳理并持续维护这些文档，是一个必要的步骤。