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的工作引擎。这种设计带来了几个关键优势零依赖与零锁定没有运行时没有包管理器没有版本升级的烦恼。你复制的是文件不是软件。你可以随时抛弃KEEL的结构你的项目代码不会因此受到任何影响。极致的可移植性和可审计性整个项目的演进历史都记录在纯文本文件中可以用任何版本控制系统如Git完美管理。代码审查者不仅可以看代码Diff还可以看LOG.md来理解每一个变更的意图和上下文。鼓励深思熟虑的设计因为所有重要决策都需要被写入文件这迫使开发者和AI代理在动手编码前必须进行充分的调研和规划。SCOPE.md文件充当了永久的、可查阅的产品需求文档和技术设计文档。2.3 三阶段工作流化繁为简的工程纪律KEEL将复杂的软件开发流程抽象为三个清晰、循环的模式这模仿了资深工程师的思维习惯SCOPE规划这是“谋定而后动”的阶段。在此阶段AI代理会像产品经理兼架构师一样与你对话深入挖掘项目愿景、功能边界、技术选型和成功标准。它还会并行进行“调研”将关于技术栈的最佳实践、潜在风险和架构模式写入文档。这个阶段的产出是经过你批准的SCOPE.md和ROADMAP.md。关键技巧在SCOPE阶段要尽可能具体和量化。例如不要只说“性能要好”而要定义“首页冷加载时间小于2秒”。这为后续的“成功标准”验证提供了明确依据。BUILD构建这是“分而治之”的执行阶段。根据ROADMAP.mdKEEL会进入一个具体的阶段如01-foundation并生成一份极其详细的PLAN.md。这份计划会将阶段目标拆解为一系列“原子任务”。每个任务都有明确的“做什么”Do和“完成标准”Done when。AI代理然后逐个执行这些任务每完成一个就提交一次Git。核心心法任务的“原子性”至关重要。一个原子任务应该小到可以在一个清晰的上下文窗口内被理解和完成其输出通常是代码变更是明确且可验证的。这大大降低了单次AI交互的复杂度。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.md3.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/目录下的核心文件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”。ROADMAP.md这是项目的时间线。它将SCOPE.md中的宏大愿景分解为一个个可顺序执行的阶段。每个阶段应该有ID和名称如01-foundation02-user-authentication。目标本阶段要达成的具体成果。状态pending待开始、active进行中、complete已完成。依赖指明需要哪些前置阶段完成才能开始本阶段。 KEEL会依据这个文件来导航整个构建过程。3.3 工坊phases/目录下的阶段文件每个阶段如01-foundation都是一个独立的工作上下文包含两个关键文件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聚焦和后续的上下文管理。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模式。它会开始向你提问对话可能如下AIKEEL好的我们进入SCOPE模式。为了构建你的“个人读书笔记管理API”我需要了解一些关键信息来创建SCOPE.md和ROADMAP.md。愿景请用一两句话描述这个API的核心目标和它为用户解决的主要问题。技术栈你倾向于使用哪些技术和框架例如Node.js/Express Python/FastAPI Go/Gin 数据库选择等核心功能列出你希望API具备的主要端点或功能例如添加书籍、记录笔记、按标签搜索笔记等。边界在初始版本v1中有哪些功能是你明确不打算实现的成功标准我们如何判断这个项目是成功的请提供一些可衡量的指标。你逐一回答后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。”生成计划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批准与执行你审查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重复此过程。阶段交付SHIP当所有原子任务都显示为完成状态后你告诉AI“第一阶段任务已完成进入SHIP模式。” AI会重新验证PLAN.md中每个任务的“Done when”标准。可能运行一轮pytest来确保基础测试通过。在LOG.md末尾撰写详细的阶段总结。将ROADMAP.md中01-foundation的状态从active更新为complete。输出总结信息“Phase 01 complete. Ready for Phase 02.”上下文重置与下一阶段你再次清空对话上下文。开启新会话说“开始第二阶段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钩子秘密检测扫描暂存区的文件防止意外提交.env、api-keys.txt等包含敏感信息的文件。这是一个重要的安全网。日志完整性警告如果你正在一个活跃的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的过程中你可能会遇到一些典型情况AI代理不按PLAN.md执行或跳过了任务可能原因上下文窗口可能包含了太多与当前任务无关的旧代码或讨论干扰了AI的判断。解决方案立即清空当前对话上下文。开启一个新会话并明确指令“请严格依据docs/phases/02-core-features/PLAN.md中的任务列表从任务X开始继续执行。” 确保AI在干净的上下文中重新读取了最新的计划文件。LOG.md记录混乱或缺失可能原因在BUILD模式中AI可能忙于写代码而忘记了更新日志。解决方案这是一个需要训练的交互习惯。当AI完成一个任务并输出结果后你可以手动提醒“请将本次任务执行情况记录到当前阶段的LOG.md中然后进行Git提交。” 经过几次提醒AI通常会形成习惯。此外pre-commit钩子的警告也会起到辅助作用。阶段依赖复杂下一个阶段需要大量参考前一阶段的代码可能原因阶段划分不够合理或者存在紧密的耦合。解决方案回顾SCOPE.md和阶段划分。理想的阶段应该是相对独立的模块。如果必须紧密依赖在ROADMAP.md中明确写明依赖关系并在前一阶段的LOG.md的“Carry Forward”部分详细说明哪些设计决策、接口约定或核心代码文件是下一阶段必须知晓的。这样在新阶段开始时AI可以通过阅读这些总结来获取关键上下文而无需加载所有源码。项目进行到一半想修改技术栈或架构解决方案这正是KEEL的优势所在。不要直接在代码上硬改。首先暂停当前的BUILD循环。然后开启一个新的SCOPE会话可以基于当前项目。你可以说“我们需要重新评估技术栈考虑将数据库从SQLite迁移到PostgreSQL。请更新SCOPE.md中的相关部分并在00-research/RESEARCH.md中补充迁移策略和风险评估。” 待新的设计和研究文档被批准后再更新ROADMAP.md可能需要在当前阶段之后插入一个新的“数据迁移”阶段。这保证了架构变更的决策过程被完整记录且不影响已有代码的清晰历史。KEEL不是一个魔法棒它是一套严谨的工作方法。它最大的价值是迫使开发者和AI代理进行结构化思考并将思考过程外化为可持久化、可审查的文档。它可能在一开始显得有些“仪式感”但一旦习惯你会发现自己对复杂项目的掌控力大大增强与AI合作的产出也变得前所未有的稳定和可靠。它让AI辅助编程从一种随机的、充满不确定性的对话变成了一种可预测、可管理、可重复的工程流程。