KEEL框架：用文件系统解决AI编码代理的上下文遗忘问题

1. 项目概述：KEEL，一个为AI编码代理设计的零安装文件框架

如果你和我一样，深度依赖Claude Code、Cursor这类AI编码助手来构建项目，那你一定体会过那种“上下文腐烂”带来的痛苦。项目进行到一半，你发现AI开始忘记早期的架构决策，代码风格开始走样，甚至漏掉你反复强调的关键需求。这就像和一个记忆力只有五分钟的搭档合作，你得不停地把说过的话再说一遍。KEEL框架的出现，就是为了彻底解决这个问题。它不是一个需要你npm install的库，也不是一个复杂的命令行工具，它只是一套精心设计的文件和目录结构。你把它复制到你的项目里，它就成了你和AI代理之间永不遗忘的“项目大脑”。

KEEL的核心思想极其简单：让文件成为框架，让磁盘成为记忆体。它通过三个明确的模式——SCOPE（规划）、BUILD（构建）、SHIP（交付）——来结构化整个开发流程。所有项目状态，从最初的愿景到每个原子任务的执行日志，都以人类可读的Markdown形式保存在docs/目录下。而.claude/CLAUDE.md文件则包含了驱动AI代理完成这一切的完整指令集。当你因为上下文窗口已满而不得不开启一个新会话时，AI代理只需要重新读取这些文件，就能立刻恢复到之前的工作状态，仿佛从未中断。这特别适合需要多轮会话、长期演进的中大型项目，无论是全栈Web应用、工具库还是复杂的脚本。

2. 核心设计哲学：为什么“只有文件”是革命性的

2.1 直面“上下文腐烂”的根源

在深入KEEL的细节之前，我们必须先理解它要解决的核心问题：为什么AI代理在长会话中会“退化”？这不仅仅是记忆问题。随着对话轮次和代码量的增加，模型的注意力机制会逐渐被海量信息稀释。早期的重要指令（比如“使用TypeScript严格模式”、“遵循RESTful API设计规范”）会被淹没在后续的代码块和问题讨论中。模型在生成新内容时，会更多地受到临近上下文的影响，而忽略掉远端的、但可能是奠基性的约束。这就是“上下文腐烂”，它导致输出质量不可预测地漂移。

传统的应对方式是不断在对话中重复关键指令，或者手动整理一份冗长的“系统提示词”并祈祷模型能记住。这两种方法都效率低下且不可靠。KEEL的解决方案是釜底抽薪：既然模型的“工作记忆”不可靠，那我们就不依赖它。我们将所有必须持久化的状态——项目规范、技术栈决策、阶段计划、完成日志——全部卸载到文件系统中。AI代理的每次“思考”都基于对磁盘文件的读取，而非对对话历史的回忆。

2.2 文件即接口，Markdown即协议

KEEL选择Markdown作为状态存储格式，是一个深思熟虑的、堪称优雅的设计决策。首先，Markdown是人类和机器都能轻松阅读和解析的格式。作为开发者，你可以随时打开SCOPE.md或任何LOG.md文件，快速了解项目全貌或某个阶段的具体执行情况，无需学习任何专有格式。其次，当前主流的AI编码代理（Claude、GPT、Gemini等）对Markdown的解析和生成能力都非常出色。这意味着KEEL框架本身几乎没有任何兼容性成本——只要你的AI助手能读文件、写Markdown，它就能成为KEEL的工作引擎。

这种设计带来了几个关键优势：

1. 零依赖与零锁定：没有运行时，没有包管理器，没有版本升级的烦恼。你复制的是文件，不是软件。你可以随时抛弃KEEL的结构，你的项目代码不会因此受到任何影响。
2. 极致的可移植性和可审计性：整个项目的演进历史都记录在纯文本文件中，可以用任何版本控制系统（如Git）完美管理。代码审查者不仅可以看代码Diff，还可以看LOG.md来理解每一个变更的意图和上下文。
3. 鼓励深思熟虑的设计：因为所有重要决策都需要被写入文件，这迫使开发者和AI代理在动手编码前，必须进行充分的调研和规划。SCOPE.md文件充当了永久的、可查阅的产品需求文档和技术设计文档。

2.3 三阶段工作流：化繁为简的工程纪律

KEEL将复杂的软件开发流程抽象为三个清晰、循环的模式，这模仿了资深工程师的思维习惯：

1. SCOPE（规划）：这是“谋定而后动”的阶段。在此阶段，AI代理会像产品经理兼架构师一样与你对话，深入挖掘项目愿景、功能边界、技术选型和成功标准。它还会并行进行“调研”，将关于技术栈的最佳实践、潜在风险和架构模式写入文档。这个阶段的产出是经过你批准的SCOPE.md和ROADMAP.md。关键技巧：在SCOPE阶段，要尽可能具体和量化。例如，不要只说“性能要好”，而要定义“首页冷加载时间小于2秒”。这为后续的“成功标准”验证提供了明确依据。

2. BUILD（构建）：这是“分而治之”的执行阶段。根据ROADMAP.md，KEEL会进入一个具体的阶段（如01-foundation），并生成一份极其详细的PLAN.md。这份计划会将阶段目标拆解为一系列“原子任务”。每个任务都有明确的“做什么”（Do）和“完成标准”（Done when）。AI代理然后逐个执行这些任务，每完成一个就提交一次Git。核心心法：任务的“原子性”至关重要。一个原子任务应该小到可以在一个清晰的上下文窗口内被理解和完成，其输出（通常是代码变更）是明确且可验证的。这大大降低了单次AI交互的复杂度。

3. SHIP（交付）：这是“关门复盘”的收尾阶段。在一个阶段的所有原子任务完成后，KEEL不会立即跳入下一阶段。它会重新审视PLAN.md中列出的所有“成功标准”，运行测试，并生成最终的LOG.md。这个日志不仅记录了做了什么，还会总结经验教训、遗留问题和需要带到下一阶段的事项。然后，ROADMAP.md中的阶段状态会被更新，上下文被清空，团队精神饱满地进入下一个循环。

这个工作流的核心魔力在于阶段间的上下文隔离。在完成01-foundation阶段并提交了LOG.md后，你可以放心地清空与AI代理的整个对话历史。当开始02-core-features时，AI代理只需要读取SCOPE.md、ROADMAP.md和01-foundation/LOG.md，就能获得启动所需的所有上下文，完全不会受到之前大量代码讨论的“信息污染”。这保证了每个阶段都在一个“干净”的认知环境中开始，最大程度保持了AI输出的一致性和高质量。

3. 项目结构与文件详解：骨架是如何搭建的

理解KEEL，就是理解它的目录和文件。让我们深入看看一个典型的KEEL项目骨架，以及每个文件扮演的角色。

your-awesome-project/ ├── .claude/ │ └── CLAUDE.md ← 【指令核心】AI代理的“操作系统” └── docs/ ├── SCOPE.md ← 【项目宪法】愿景、范围、技术栈、成功标准 ├── ROADMAP.md ← 【演进地图】阶段划分与状态追踪 └── phases/ ← 【执行实录】每个阶段的工作区 ├── 00-research/ │ └── RESEARCH.md ← 【技术雷达】架构调研与决策依据 ├── 01-foundation/ │ ├── PLAN.md ← 【作战图纸】原子任务分解 │ └── LOG.md ← 【任务报告】执行记录与阶段总结 └── 02-core-features/ ├── PLAN.md └── LOG.md

3.1 大脑：.claude/CLAUDE.md

这是整个框架的“智能引擎”。它不是一个简单的提示词，而是一份详尽的、自包含的操作手册，指导AI代理如何扮演KEEL框架所定义的角色（规划师、架构师、执行者）。其内容通常包括：

• 角色定义：明确告知AI“你现在是KEEL引擎”，需要遵循特定的工作模式。
• 模式切换逻辑：如何根据用户的指令或项目状态，在SCOPE、BUILD、SHIP模式间切换。
• 文件读写规范：精确说明如何读取SCOPE.md、ROADMAP.md，如何创建和更新PLAN.md、LOG.md。
• 原子任务定义：指导如何将模糊的需求拆解为具体、可验证、可执行的原子任务。
• Git提交规范：规定提交信息的格式（如keel(01): task 1 — initialize project），以保持历史清晰。
• 对话引导：包含如何主动向用户提问以澄清需求，以及在遇到阻塞时如何寻求帮助。

实操要点：你通常不需要直接修改CLAUDE.md，除非你想深度定制KEEL的行为。对于大多数项目，使用官方模板即可。它的强大之处在于，一旦被AI代理加载，后续所有的交互都基于这份“宪法”，保证了行为的一致性。

3.2 基石：docs/目录下的核心文件

1. SCOPE.md：这是项目的源头。它应该在SCOPE模式初期，由你和AI代理共同填满。一份好的SCOPE.md就像一份高质量的产品需求文档（PRD）加技术方案设计（TSD）。它必须回答以下问题：

   • Vision（愿景）：用一两句话说明这个项目要解决的根本问题。
   • Stack（技术栈）：明确到具体版本和配置（如“Next.js 14 with App Router, Supabase with Row Level Security enabled”）。
   • Features（功能）：用列表形式列出核心功能点，最好能区分MVP（最小可行产品）和未来迭代。
   • Boundaries（边界）：明确说明“不做”什么，这能有效防止项目范围蔓延。
   • Success Criteria（成功标准）：必须是可衡量、可验证的指标（如“用户注册流程端到端测试通过率100%”、“API p95延迟 < 200ms”）。

2. ROADMAP.md：这是项目的时间线。它将SCOPE.md中的宏大愿景分解为一个个可顺序执行的阶段。每个阶段应该有：

   • ID和名称：如01-foundation，02-user-authentication。
   • 目标：本阶段要达成的具体成果。
   • 状态：pending（待开始）、active（进行中）、complete（已完成）。
   • 依赖：指明需要哪些前置阶段完成才能开始本阶段。 KEEL会依据这个文件来导航整个构建过程。

3.3 工坊：phases/目录下的阶段文件

每个阶段（如01-foundation）都是一个独立的工作上下文，包含两个关键文件：

1. PLAN.md：在BUILD模式开始时，由AI代理根据阶段目标生成。它是行动的蓝图。一个优秀的计划应该：

   • 任务原子化：每个任务都应该小到足以在一个AI响应中完成并验证。例如，“创建用户模型Prisma Schema”是一个任务，“实现用户注册API端点”是另一个任务。
   • 标准可验证：“Done when”必须描述一个客观的、可检查的状态。例如，“Done when: Runningnpm testpasses all unit tests for the new API endpoint”，而不是“Done when: API is working”。
   • 产出明确：指明任务完成后会产生或修改哪些文件，这有助于AI聚焦和后续的上下文管理。

2. LOG.md：在BUILD模式中，随着每个原子任务的完成而逐步填充；在SHIP模式中，进行最终总结。它既是工作日志，也是交接文档。内容包括：

   • 任务执行记录：每个任务何时开始、结束，遇到了什么问题，如何解决。
   • 代码变更摘要：简述本次提交修改了哪些文件，目的是什么。
   • 阶段总结：在SHIP时撰写，回顾本阶段是否达成所有成功标准，有哪些经验教训、已知问题或待办事项需要传递给下一阶段。

重要经验：phases/目录的隔离性是KEEL管理上下文的精髓。当AI在处理02-core-features/PLAN.md时，它完全不需要加载01-foundation/目录下的任何代码文件，除非那些文件被明确列为依赖。这极大地净化了每次交互的上下文，让AI专注于当前最紧要的问题。

4. 完整实操流程：从零启动一个KEEL项目

让我们通过一个具体的例子——构建一个“个人读书笔记管理API”——来走一遍KEEL的全流程。假设我们使用Claude Code作为AI代理。

4.1 初始化与SCOPE阶段

首先，我们初始化项目并进入SCOPE模式。

# 1. 克隆KEEL仓库（或直接下载模板） git clone https://github.com/diydigitaldreams/keel.git # 2. 在你的项目目录中初始化KEEL结构 # 假设你的项目目录是 `my-book-notes-api` ./keel/setup.sh /path/to/my-book-notes-api # 3. 进入项目目录，初始化Git（如果尚未初始化） cd /path/to/my-book-notes-api git init . git add . git commit -m "chore: initialize project with KEEL framework" # 4. 打开你的AI编码代理（如Claude Code），将上下文指向本项目。 # 5. 对你的AI代理说：“让我们开始规划（SCOPE）这个项目。”

此时，AI代理会读取.claude/CLAUDE.md中的指令，进入SCOPE模式。它会开始向你提问，对话可能如下：

AI（KEEL）：好的，我们进入SCOPE模式。为了构建你的“个人读书笔记管理API”，我需要了解一些关键信息来创建SCOPE.md和ROADMAP.md。

1. 愿景：请用一两句话描述这个API的核心目标和它为用户解决的主要问题。
2. 技术栈：你倾向于使用哪些技术和框架？（例如：Node.js/Express， Python/FastAPI， Go/Gin， 数据库选择等）
3. 核心功能：列出你希望API具备的主要端点或功能（例如：添加书籍、记录笔记、按标签搜索笔记等）。
4. 边界：在初始版本（v1）中，有哪些功能是你明确不打算实现的？
5. 成功标准：我们如何判断这个项目是成功的？请提供一些可衡量的指标。

你逐一回答后，AI会生成并更新docs/SCOPE.md文件。同时，它可能会并行进行一些基础调研，比如为你选择的技术栈（例如FastAPI + SQLite）撰写最佳实践建议，并存入docs/phases/00-research/RESEARCH.md。完成后，它会生成一个初步的ROADMAP.md，比如将项目分为01-foundation（基础设置）、02-book-model（书籍模型）、03-note-crud（笔记增删改查）、04-search-api（搜索API）等阶段。

你需要仔细审查SCOPE.md，确保它准确反映了你的意图。确认无误后，对AI说：“我批准这个范围规划。我们开始第一阶段（01-foundation）的构建吧。” 然后，清空当前的对话上下文。

4.2 BUILD与SHIP循环：以“01-foundation”阶段为例

清空上下文后，开启一个新的AI会话。由于项目根目录已有KEEL文件，AI代理会自动识别环境。你直接说：“我们开始构建第一阶段（01-foundation）。”

1. 生成计划：AI读取ROADMAP.md，发现01-foundation状态是pending。它会读取SCOPE.md和00-research/RESEARCH.md，然后为01-foundation阶段创建docs/phases/01-foundation/PLAN.md。这个计划可能包含如下原子任务：

   # Phase 01: Foundation ## Objective Set up the basic Python/FastAPI project structure with SQLite database connection, Pydantic models, and automated testing foundation. ### Task 1: Project scaffolding **Do:** Initialize a new Python virtual environment, install FastAPI, SQLAlchemy, Pydantic, and pytest. Create the basic directory structure (app/, tests/). **Done when:** `pip list` shows packages installed, and running `python -m pytest` (with an empty test file) executes without import errors. **Files:** `pyproject.toml`, `requirements.txt`, `app/__init__.py` ### Task 2: Database configuration **Do:** Set up SQLAlchemy with an SQLite database. Create a database connection utility and a base model class. **Done when:** A simple script can connect to `./local.db` and execute a `SELECT 1` query successfully. **Files:** `app/database.py`, `app/models/base.py` ### Task 3: Core API setup **Do:** Create the main FastAPI app instance with a health check endpoint (`GET /health`). **Done when:** Starting the dev server (`uvicorn app.main:app`) and visiting `http://localhost:8000/health` returns `{"status": "ok"}`. **Files:** `app/main.py`, `app/api/health.py`

2. 批准与执行：你审查PLAN.md，确认无误后说：“批准该计划，开始执行任务1。” AI会开始工作，完成Task 1后，它会：

   • 执行任务（创建文件、编写代码）。
   • 在01-foundation/LOG.md中记录：“Task 1 completed: Project scaffold created.”
   • 执行一次Git提交：git commit -m “keel(01): task 1 — project scaffolding with FastAPI and pytest”。 然后它自动进行到任务2，重复此过程。

3. 阶段交付（SHIP）：当所有原子任务都显示为完成状态后，你告诉AI：“第一阶段任务已完成，进入SHIP模式。” AI会：

   • 重新验证PLAN.md中每个任务的“Done when”标准。
   • 可能运行一轮pytest来确保基础测试通过。
   • 在LOG.md末尾撰写详细的阶段总结。
   • 将ROADMAP.md中01-foundation的状态从active更新为complete。
   • 输出总结信息：“Phase 01 complete. Ready for Phase 02.”

4. 上下文重置与下一阶段：你再次清空对话上下文。开启新会话，说：“开始第二阶段（02-book-model）。” AI会读取SCOPE.md、ROADMAP.md以及01-foundation/LOG.md，了解项目已具备的基础设施，然后为02-book-model创建新的PLAN.md。如此循环，直至项目完成。

关键技巧：在BUILD模式中，如果某个任务特别复杂，AI可能会建议将其进一步拆解为子任务，或者在LOG.md中记录下需要人工决策的阻塞点。这时，你应该介入提供指导，然后让AI继续。KEEL框架本身不替代你的决策，它只是让你的决策和AI的执行变得有条不紊、有迹可循。

5. 高级技巧、问题排查与生态集成

5.1 利用Git钩子实现自动化约束

KEEL提供的可选Git钩子是其“隐形守护者”。安装时默认带钩子，它们能自动执行一些质量关卡检查：

• commit-msg钩子：强制提交信息遵循keel(<phase>): <description>格式。这保证了提交历史的可读性和一致性，让你一眼就能看出某个提交属于哪个KEEL阶段。如果格式错误，提交会被拒绝。
• pre-commit钩子：
  1. 秘密检测：扫描暂存区的文件，防止意外提交.env、api-keys.txt等包含敏感信息的文件。这是一个重要的安全网。
  2. 日志完整性警告：如果你正在一个活跃的KEEL阶段目录中修改文件并尝试提交，但对应的LOG.md文件没有被更新，钩子会发出警告。这提醒你记得记录工作，保持日志的实时性。

如何绕过：在极少数需要紧急提交或调试的情况下，你可以使用git commit --no-verify来跳过钩子检查。但这应该被视为例外，而非惯例。

5.2 验证项目完整性

KEEL包含一个validate.sh脚本，这是一个非常有用的诊断工具。在项目任何位置运行它，它会给你一份项目健康报告：

$ ./validate.sh [KEEL] Validating project: . Core files: ✓ .claude/CLAUDE.md ✓ docs/SCOPE.md ✓ docs/ROADMAP.md Phases: ✓ Phase 01 [complete] — 01-foundation (LOG indicates completion) → Phase 02 [active] — 02-book-model (PLAN: yes, LOG: in progress) ✗ Phase 03 [pending] — 03-note-crud (ERROR: Directory exists but PLAN.md is missing) ○ Phase 04 [pending] — no directory yet (normal) [KEEL] Validation failed. Issues found.

如上所示，它发现了问题：03-note-crud目录被创建了（可能误操作），但里面没有PLAN.md，这与ROADMAP.md中该阶段pending的状态矛盾。这能帮你及时清理孤儿目录或纠正状态不一致的问题。

5.3 适配不同的AI编码代理

KEEL的理念是普适的，但初始模板针对Claude Code优化。将其适配到其他代理非常简单，核心是让代理能读取到CLAUDE.md中的指令：

• Cursor：将.claude/CLAUDE.md的全部内容复制到项目根目录下的.cursor/rules/keel.md文件中。Cursor会自动读取该文件作为项目级规则。
• Windsurf：将指令内容添加到项目根目录的.windsurfrules文件中，或配置其级联指令功能指向CLAUDE.md。
• 其他代理（如Codex, Gemini CLI）：原理相同，在其指定的系统提示词或指令文件位置（通常是项目根目录下以代理名命名的隐藏目录，如.codex/,.gemini/），创建一个文件（如instructions.md），并将CLAUDE.md的内容复制进去。

注意事项：不同代理对长上下文指令的解析能力有差异。如果遇到代理行为不符合预期，可以尝试将CLAUDE.md中最核心的模式切换和任务执行逻辑提取出来，制作一个更简短的版本用于其他代理。

5.4 常见问题与排查实录

在实际使用KEEL的过程中，你可能会遇到一些典型情况：

1. AI代理不按PLAN.md执行，或跳过了任务

   • 可能原因：上下文窗口可能包含了太多与当前任务无关的旧代码或讨论，干扰了AI的判断。
   • 解决方案：立即清空当前对话上下文。开启一个新会话，并明确指令：“请严格依据docs/phases/02-core-features/PLAN.md中的任务列表，从任务X开始继续执行。” 确保AI在干净的上下文中重新读取了最新的计划文件。

2. LOG.md记录混乱或缺失

   • 可能原因：在BUILD模式中，AI可能忙于写代码而忘记了更新日志。
   • 解决方案：这是一个需要训练的交互习惯。当AI完成一个任务并输出结果后，你可以手动提醒：“请将本次任务执行情况记录到当前阶段的LOG.md中，然后进行Git提交。” 经过几次提醒，AI通常会形成习惯。此外，pre-commit钩子的警告也会起到辅助作用。

3. 阶段依赖复杂，下一个阶段需要大量参考前一阶段的代码

   • 可能原因：阶段划分不够合理，或者存在紧密的耦合。
   • 解决方案：回顾SCOPE.md和阶段划分。理想的阶段应该是相对独立的模块。如果必须紧密依赖，在ROADMAP.md中明确写明依赖关系，并在前一阶段的LOG.md的“Carry Forward”部分，详细说明哪些设计决策、接口约定或核心代码文件是下一阶段必须知晓的。这样，在新阶段开始时，AI可以通过阅读这些总结来获取关键上下文，而无需加载所有源码。

4. 项目进行到一半，想修改技术栈或架构

   • 解决方案：这正是KEEL的优势所在。不要直接在代码上硬改。首先，暂停当前的BUILD循环。然后，开启一个新的SCOPE会话（可以基于当前项目）。你可以说：“我们需要重新评估技术栈，考虑将数据库从SQLite迁移到PostgreSQL。请更新SCOPE.md中的相关部分，并在00-research/RESEARCH.md中补充迁移策略和风险评估。” 待新的设计和研究文档被批准后，再更新ROADMAP.md，可能需要在当前阶段之后插入一个新的“数据迁移”阶段。这保证了架构变更的决策过程被完整记录，且不影响已有代码的清晰历史。

KEEL不是一个魔法棒，它是一套严谨的工作方法。它最大的价值是迫使开发者和AI代理进行结构化思考，并将思考过程外化为可持久化、可审查的文档。它可能在一开始显得有些“仪式感”，但一旦习惯，你会发现自己对复杂项目的掌控力大大增强，与AI合作的产出也变得前所未有的稳定和可靠。它让AI辅助编程从一种随机的、充满不确定性的对话，变成了一种可预测、可管理、可重复的工程流程。