1. 项目概述为AI编程助手构建结构化记忆如果你和我一样长期使用Claude、Cursor或者GitHub Copilot这类AI编程助手一定遇到过这样的困境每次开启一个新会话都像是面对一个失忆的伙伴。你得重新解释一遍项目的来龙去脉、架构设计、上周刚做的关键决策以及为什么某个模块要那么写。你可能会维护一个巨大的CLAUDE.md或AGENTS.md文件但它很快会变成一堵无法维护的“文字墙”里面混杂着产品愿景、技术细节和临时决定信息熵不断增大最终连你自己都懒得更新。更令人沮丧的是那些依赖向量数据库Vector Store的长期记忆方案在实践中往往表现不佳。它们试图记住“一切”却分不清什么才是真正重要的。它们会忘记产品的核心灵魂为什么这个项目存在却可能牢牢记住某个临时调试用的测试函数。问题的根源在于大多数记忆系统缺乏一个清晰、分层的结构来区分不同性质的信息。这正是LLM Context Protocol (LCP)要解决的问题。它不是一个复杂的服务也不是一个需要嵌入模型Embeddings的向量库。LCP是一个极其简单却强大的理念通过纯文件、纯JSON为你的项目建立一个分层的、结构化的记忆系统。它把项目知识清晰地划分为三个层次让任何能读取文件的AI智能体都能在会话开始时快速、完整地重建对你项目的认知。没有外部依赖没有厂商锁定只有可读、可版本控制、可审计的文本文件。2. LCP核心设计哲学三层分离各司其职LCP的精髓在于“分离关注点”Separation of Concerns这是软件工程中的经典原则被巧妙地应用到了项目上下文管理上。它将项目知识严格地划分为三个独立的层次每个层次都有其独特的使命和更新频率。2.1 全局层项目的“灵魂”与“宪法”Global Layer存储的是项目的本质。你可以把它想象成项目的“宪法”或“灵魂宣言”。它回答的是最根本的问题这个产品交付什么价值(What this product delivers)它解决了谁的什么痛苦(What problem it solves for whom)为什么现有的市场方案不够好(Why existing solutions fall short)用户使用时应获得怎样的感受(What feeling the user should have)哪些产品选择会背叛这个本质(Things this product must never do)这个文件的变化频率极低只会在产品的根本性定位、目标用户或核心价值主张发生改变时例如公司战略转型才需要更新。在99%的日常开发中它都是稳定不变的。它为所有技术决策提供了最高级别的指导和约束。例如一个定位为“极简、专注的笔记应用”其Global层会明确规定“必须永不添加社交功能”这直接否决了任何关于“添加好友动态流”的提议。2.2 基线层项目的“活体解剖图”Baseline Layer描述的是项目当前活生生的技术结构。它就像一份随时更新的“架构解剖图”包含了核心模块/组件及其职责。模块之间的交互关系与数据流。关键的技术栈与依赖。部署与运行环境概况。Baseline会在项目的架构发生实质性变化时更新例如新增了一个微服务、重构了数据访问层、或者引入了一个新的核心第三方库。它不关心“为什么”要这么改那是Delta层的事它只客观记录“现在是什么样子”。这确保了AI助手始终对项目的当前结构有一个准确的认知不会基于过时的架构图提出建议。2.3 增量层项目的“决策日志”Delta Layer是最高频更新的层次它以批次Batch为单位记录开发过程中的具体决策。每一次完成一个经过评审或确认的工作批次比如合并一个Pull Request完成一个功能模块就应该生成一个Delta文件。每个Delta文件都是一个独立的故事包含发生了什么变化(What changed)文件列表、代码片段对比摘要。为什么这么变(Why)决策背后的原因、权衡的选项、解决的问题。谁做的决定(Who decided)明确记录决策来源是“用户”、“AI助手”还是“共识”。观察到了什么(What was observed)新方案的效果、遇到的意外问题、学到的经验。Delta文件按时间戳命名如2023-11-05-143022-refactor-auth-api.json形成一个严格按时间排序的决策历史流。AI助手通过按顺序“重放”Replay这些Delta就能身临其境地理解项目是如何一步步演进到今天的理解每一个看似奇怪的代码背后可能都有一个合理的历史原因。注意三层之间严禁信息冗余。Global里不能出现技术细节Baseline里不能复述决策理由Delta里不能重新定义架构。这种强制分离保证了信息的清晰度和维护性。3. 协议运作机制读写分离与确定性重建LCP不仅定义了存储什么更定义了一套清晰的读写协议确保上下文重建过程是确定性和高效的。3.1 读取顺序AI助手的“上岗培训”流程当一个AI助手或任何工具在一个新会话中需要理解你的项目时它会遵循一个固定的读取顺序。这个顺序是精心设计的从抽象到具体从稳定到动态定位项目首先读取context-library/projects-index.json。这个文件相当于一个工作空间注册表列出所有项目及其元数据。助手通过它找到当前活跃项目的标识符和对应文件的路径。理解灵魂接着读取对应项目的Global文件如context-library/global/myapp.json。这是第一课让助手牢牢记住“我们是谁我们为何而战”。所有后续的建议都必须在这个框架内进行。掌握现状然后读取当前Baseline文件如context-library/baselines/myapp/baseline-current.json。助手由此获得项目的技术蓝图知道各个部件在哪里如何连接。重温历史最后按时间顺序读取该项目Delta目录下的所有JSON文件。助手像看日记一样了解项目演进过程中的每一个关键决策、每一次转折。这赋予了它“经验”和“上下文”让它能理解为什么代码是现在这个样子。这个流程确保了一个全新的AI助手能在几分钟内获得一个资深开发者对该项目的认知深度而且每次获得的信息都是一致的。3.2 写入时机与工作流集成的“记忆快照”LCP的写入操作与你的开发工作流紧密耦合主要发生在完成一个有意义的工作单元之后。Delta每次提交后这是强制动作。每次你完成、评审并批准一批更改例如合并一个功能分支就应该生成一个Delta文件。这不仅仅是记录代码差异Git已经做了重点是记录决策逻辑。例如“为什么选择库A而不是库B因为库A的包体积小50%虽然文档略差但我们的使用场景简单。”Baseline架构变更后当你的更改涉及架构层面的调整时在生成Delta之后还需要更新Baseline文件。例如你从单体应用拆出了一个独立的用户服务那么就需要在Baseline中新增这个服务模块并更新模块间的关系图。Global本质变更后极少发生。只有当产品方向、核心价值主张或目标用户群体发生根本性变化时才需要更新。比如你的项目从一个“内部效率工具”转型为一个“面向公众的SaaS产品”。4. 实战部署从零搭建你的项目记忆库理论说完了我们来点实际的。下面是一套手把手将LCP集成到你现有项目中的步骤。4.1 初始化目录结构在你的项目根目录下创建标准的LCP目录结构。我强烈建议将这个目录加入你的版本控制系统如Git。# 在你的项目根目录下执行 mkdir -p context-library/{global,baselines,deltas}创建后的结构如下your-project/ ├── src/ ├── ... (你的其他项目文件) └── context-library/ # LCP根目录 ├── projects-index.json ├── global/ # 存放全局层文件 ├── baselines/ # 存放基线层文件 └── deltas/ # 存放增量层文件4.2 配置项目索引文件projects-index.json是你的工作空间中枢。如果你只有一个项目它看起来也很简单。{ workspace_id: my-personal-workspace, projects: [ { project_id: taskflow-api, display_name: TaskFlow 后端API, root_path: /Users/yourname/Projects/taskflow-api, global_ref: context-library/global/taskflow-api.json, baseline_ref: context-library/baselines/taskflow-api/baseline-current.json, delta_dir: context-library/deltas/taskflow-api, status: active } ] }关键字段解析project_id: 项目的机器友好标识符全小写用连字符在文件路径中使用。root_path: 项目的绝对路径。这有助于AI助手定位项目内的其他文件。*_ref和delta_dir: 指向各层文件的相对路径相对于context-library目录。这种设计保持了灵活性。4.3 撰写你的项目“宪法”全局层这是最有价值也最需要深思熟虑的一步。召集你的团队如果可能一起回答下面这些问题并填入global/your-project-id.json。{ project_id: taskflow-api, essencia: { o_que_esse_produto_vende: 一个极简、零配置的团队任务自动化API服务。它出售的是‘时间’和‘确定性’通过将重复性工作流转化为可编程、可监控的API解放团队创造力。, que_problema_ele_resolve: 中小型技术团队内部存在大量手工、重复的运维、数据同步、状态同步任务。这些任务琐碎、易错、无人爱做且打断深度工作流。现有方案如Zapier、n8n对于技术团队而言过于黑盒、定制性差且成本高。, quem_sofre_com_esse_problema: 10-50人规模的技术团队负责人、全栈工程师、DevOps工程师。他们懂代码需要灵活性和控制力但没有精力为每一个小需求搭建和维护一套系统。, por_que_a_solucao_atual_do_mercado_nao_basta: 低代码/无代码平台Zapier隐藏了逻辑调试困难且按触发次数收费成本不可控。自建脚本则面临部署、监控、维护的持续开销容易变成‘祖传脚本’无人敢动。, qual_sensacao_o_usuario_deve_ter: 用户应该感到‘轻松掌控’和‘恍然大悟’。他们能像搭积木一样组合API实时看到任务流的状态和日志并且对系统行为有完全的预见性和解释权。, quais_escolhas_de_produto_seriam_traicao_a_essencia: [ 变成一个需要复杂拖拽界面配置的平台。, 隐藏任务执行逻辑变成黑盒。, 按执行次数进行阶梯式收费让用户不敢多用。, 增加社交、聊天等与核心工作流无关的功能。, 追求大而全试图替代Jenkins、Airflow等专业调度系统。 ] } }实操心得撰写Global文件时要像写产品宣言一样充满激情和原则性。把它打印出来贴在墙上都不为过。它将是未来所有技术争论的“最高法”。当AI助手提议一个花哨的功能时你可以直接问“这个提议符合我们Global里定义的‘绝不成为’的条款吗”4.4 绘制第一版技术蓝图基线层在baselines/your-project-id/目录下创建baseline-current.json。这里描述你项目当前的技术状态。{ project_id: taskflow-api, version: 1.0, as_of: 2023-11-05T10:00:00Z, architecture_overview: 这是一个基于Go语言的单体API服务采用清晰的分层架构。外部触发通过Webhook或API调用进入由工作流引擎解析并执行预定义的任务链。状态和日志持久化到PostgreSQL缓存使用Redis。, core_modules: [ { name: API Gateway, purpose: 接收外部HTTP/Webhook请求进行认证、限流和路由转发。, tech_stack: [Go, Gin框架], dependencies: [Auth Service, Workflow Engine] }, { name: Workflow Engine, purpose: 核心引擎。解析任务定义DSL调度任务执行器处理错误与重试。, tech_stack: [Go], dependencies: [Task Executors, State Manager] }, { name: Task Executors, purpose: 一组可插拔的执行器用于执行具体动作如调用HTTP API、查询数据库、发送邮件。, tech_stack: [Go], dependencies: [State Manager, External Services] } ], data_stores: [ { name: PostgreSQL, role: 主数据库。存储工作流定义、执行历史、用户配置。, version: 15 }, { name: Redis, role: 缓存与分布式锁。缓存频繁访问的工作流定义协调多实例下的任务调度。, version: 7 } ], deployment: { environment: 使用Docker容器化部署通过Kubernetes编排。配置通过环境变量注入。 } }4.5 记录你的第一个决策增量层完成第一个功能后在deltas/your-project-id/目录下创建一个以时间戳命名的文件例如2023-11-05-143022-initial-auth-setup.json。{ project_id: taskflow-api, delta_id: 2023-11-05-143022-initial-auth-setup, title: 实现基于JWT的API认证层, timestamp: 2023-11-05T14:30:22Z, summary: 为API Gateway添加了JWT令牌的签发与验证中间件定义了基本的用户角色admin, user。, changes: [ { type: added, path: internal/auth/jwt.go, description: JWT工具函数包含生成、解析、验证令牌。 }, { type: added, path: internal/middleware/auth.go, description: Gin中间件用于验证请求头中的Bearer Token并设置用户上下文。 } ], decision_origin: user, reasoning: 项目需要基本的访问控制。评估了API Key和JWT两种方案。选择JWT是因为1) 无状态适合API服务扩展2) 可内嵌声明如角色减少数据库查询3) 行业标准生态完善。明确排除了OAuth 2.0因为当前是内部服务无需复杂的第三方授权流程。, observed_behavior: 中间件工作正常未授权请求返回401。后续需要添加速率限制中间件与之配合。, links: [PR#12] }关键字段解析decision_origin: 这是LCP一个非常出色的设计。它明确记录了决策的权威来源。是“用户”你最终拍板的还是“AI助手”在权限内自主决定的或者是讨论后的“共识”这避免了日后对“这个蠢决定是谁做的”的无谓争论。reasoning: 这是Delta的灵魂。不仅要写“做了什么”更要写“为什么这么做以及为什么不那么做”。这为未来的维护者和AI提供了宝贵的决策上下文。5. 与主流AI助手集成实战LCP是协议不是软件。你需要让你的AI助手学会读取它。以下是针对不同工具的集成思路。5.1 通用集成方案任何能读文件的AI对于任何支持上传文件或读取项目文件的AI助手如OpenAI的ChatGPT with Code Interpreter或任何自定义Agent集成流程是标准化的。会话初始化脚本在开始对话前让AI先执行一个“读取上下文”的指令。你可以提供一个提示词模板“请先按照LLM Context Protocol (LCP) 读取并理解本项目。请依次读取以下文件并总结出项目的核心本质、当前技术架构和近期关键决策历史./context-library/projects-index.json./context-library/global/taskflow-api.json./context-library/baselines/taskflow-api/baseline-current.json./context-library/deltas/taskflow-api/目录下按时间排序的所有.json文件。 完成阅读后请用一句话告诉我你理解的本项目是什么。”将提示词模板化你可以将上述指令保存在一个如onboard-agent.md的文件中每次新会话时直接粘贴给AI。5.2 与 Cursor 深度集成Cursor因其强大的项目感知能力是实践LCP的绝佳伙伴。利用.cursor/rules目录在项目根目录创建.cursor/rules目录将你的Global文件核心内容提炼成Cursor规则。例如创建一个product-essence.md# 项目核心原则 (源自LCP Global) - **我们是什么**极简、零配置的团队任务自动化API。 - **核心价值**出售“时间”和“确定性”解放创造力。 - **绝不成为**复杂拖拽平台、黑盒系统、按次付费产品、社交应用、大而全的调度系统。 - **用户感受**轻松掌控恍然大悟。Cursor会在编写代码时参考这些规则。在Chat中引用上下文当你在Cursor Chat中讨论新功能时可以主动引用LCP文件。“根据我们LCP的Baseline当前认证是JWT中间件。现在我们需要添加一个API Key认证方式给机器调用。请参考baseline-current.json中的API Gateway模块设计一个兼容的方案并说明如何更新Baseline。”自动化Delta生成进阶你可以编写一个简单的Git钩子post-commit hook或使用Cursor的自定义命令在提交信息中提取关键信息自动生成Delta文件的骨架你只需要补充reasoning部分即可。5.3 与 Claude Code 或 Claude Desktop 配合Claude对长上下文和文件的理解能力很强。直接上传上下文文件开始新会话时直接将整个context-library目录作为文件上传给Claude。然后给出指令“你已获得本项目遵循LLM Context Protocol (LCP) 存储的所有上下文。请基于这些信息作为本项目的资深技术伙伴与我协作。首先请复述一下我们项目的核心本质和最近一次重大架构决策是什么。”引导Claude使用结构化思维当你向Claude提出一个复杂问题时可以引导它参考特定层。“我们需要优化工作流引擎的性能。请先回顾Baseline中‘Workflow Engine’模块的当前描述然后查看Deltas目录中所有与‘性能’、‘引擎’相关的决策历史最后给我提出三个优化方案并分析每个方案与项目Global原则的契合度。”5.4 在 GitHub Copilot 或 AGENTS.md 中嵌入指引对于依赖AGENTS.md或类似指令文件的工具LCP不是替代而是补充。在你的AGENTS.md文件顶部添加# 项目上下文总览 本项目遵循LLM Context Protocol (LCP) 管理结构化记忆。在提供任何建议前请务必理解以下核心原则详见 context-library/global/ - 核心价值[从Global中提炼一句话] - 技术边界[从Global中提炼“绝不成为”的要点] - 当前架构快照请参考 context-library/baselines/*/baseline-current.json。 - 决策历史重要决策原因记录在 context-library/deltas/ 中。 **首要规则**所有建议必须符合项目的核心本质不得提议属于“绝不成为”列表中的功能。这样Copilot在生成代码或建议时会有一个高级别的原则性约束。6. 高级实践与经验心得使用LCP一段时间后我总结出一些能极大提升效率的经验和需要避开的“坑”。6.1 Delta文件的撰写艺术不只是记录“What”更是阐明“Why”写一个好的Delta文件是门艺术。避免写成Git提交记录的翻版。反面例子无用summary: 修复了登录bug, reasoning: 用户报告无法登录。正面例子有价值summary: 将JWT密钥从配置文件移至环境变量并修复了过期时间解析逻辑。, reasoning: 1) 安全加固密钥不应硬编码在配置文件中遵循12-Factor App原则。评估了密钥管理服务如Vault但鉴于项目初期复杂度先采用环境变量。2) Bug根因发现time.ParseDuration对720h30天的解析在特定时区下出错改用time.Hour * 24 * 30显式计算。这提醒我们时间处理库的‘便捷’函数可能存在隐晦的边界情况。, decision_origin: consensus, observed_behavior: 部署后登录正常密钥轮换流程可通过更新环境变量完成无需重启服务感谢热加载配置设计。心得reasoning字段是给未来自己或AI的“决策备忘录”。多花两分钟写清楚权衡过程未来可能节省两小时的理解成本。6.2 Baseline的维护何时更新谁来更新Baseline不是每天都要改的东西。我遵循一个简单的规则当你的架构图无论是脑中的还是画在白板上的发生了值得用方框和箭头重新画一遍的变化时才更新Baseline。需要更新Baseline的情况新增或移除一个核心服务/模块。改变了主要模块之间的通信方式如从HTTP REST改为gRPC。引入或更换了核心的数据存储/缓存技术。部署架构发生重大变化如从单机部署改为K8s集群。不需要更新Baseline的情况在现有模块内添加新的API端点。优化了某个函数的算法。更新了第三方库的版本除非这个更新带来了架构性影响如从MySQL驱动切换到PostgreSQL驱动。通常在合并一个涉及架构变动的Pull Request后在生成Delta文件的同时由该PR的主要负责人来更新Baseline。可以将此作为Code Review的一项检查内容。6.3 处理多项目与微服务场景LCP的projects-index.json天然支持多项目工作空间。对于微服务架构你有两种策略单一项目多模块Baseline如果你的所有微服务都在一个代码仓库Monorepo中且联系紧密可以将其视为一个LCP项目。在Baseline的core_modules里每个微服务就是一个模块并详细描述服务间的API契约和通信方式。多项目关联索引如果每个微服务是独立的仓库则为每个服务创建一个独立的LCP项目。你可以在每个服务的Global文件中通过描述性文字说明它与其他服务的关系。甚至可以在projects-index.json中为项目添加自定义的tags字段如tags: [order-system, depends-on:user-service]来建立隐式关联。6.4 版本控制与协作context-library目录应该被纳入Git版本控制。这带来了巨大好处历史追溯你可以看到Global原则是如何演变的Baseline架构是如何成长的就像看代码历史一样。协作透明团队成员对项目的核心认知和决策历史有统一的、可查询的来源。分支与合并对于重大的、探索性的功能分支你甚至可以创建分支专属的Delta文件或临时的Baseline变体在合并时再决定如何整合到主干的上下文中。重要提醒Global文件极少变更一旦变更往往是重大的。建议对其修改进行严格的Code Review甚至需要团队核心成员达成共识。7. 常见问题与排查技巧实录在实际推广和使用LCP的过程中我和团队遇到了一些典型问题以下是我们的解决方案。7.1 问题感觉维护LCP增加了额外开销团队不愿意写Delta。分析与解决这是最常见的初期阻力。关键在于转变观念不把LCP视为“额外的文档”而是视为“智能开发的必要投入”。技巧1与工作流绑定将生成Delta作为合并PR的强制检查项。在PR模板中增加一节“决策记录”要求填写变更摘要和理由。这个内容可以直接粘贴到未来的Delta文件里。技巧2简化起步初期不要追求完美。Delta文件可以只是一个简单的JSON哪怕只写了summary和reasoning两个字段其价值也远大于没有。可以逐步完善字段。技巧3让AI帮忙写在PR描述或提交信息中用自然语言描述你的更改和原因。然后可以让AI助手如Claude根据你的描述帮你格式化成结构化的Delta JSON骨架。你只需要做最终审核和润色。7.2 问题Baseline文件很快过时与实际代码不同步。分析与解决这违背了LCP的初衷。Baseline必须是“活”的文档。建立更新纪律在团队章程中约定任何导致架构图变化的修改必须同步更新Baseline。可以将此作为代码审查CR的必审项。利用自动化检查进阶可以编写简单的脚本在CI/CD流水线中做基础检查。例如检查如果修改了特定目录如/pkg/service的结构或接口文件但没有修改Baseline文件则发出警告。但这只是辅助核心还是靠文化。7.3 问题AI助手似乎没有正确理解或使用上下文。分析与解决这通常是提示词或集成方式不完善导致的。检查读取顺序确认你是否明确指示AI按Global - Baseline - Deltas的顺序阅读。AI需要明确的指令。提供结构化查询示例不要只说“参考上下文”。给出具体例子“请根据Baseline中‘数据存储’部分评估为PostgreSQL添加读写分离的必要性并参考Deltas中关于‘数据库’的历史决策。”测试AI的理解在会话开始让AI用一两句话复述项目的核心本质和最新架构。如果它复述错了说明它没读对文件或没理解你需要纠正并引导它重新阅读。7.4 问题Delta文件太多新会话时全部读取会导致上下文令牌Token超限。分析与解决这是使用任何长上下文系统都会面临的现实问题。策略1摘要式读取不要要求AI在会话开始时通读所有Delta文件。而是指示它“请读取最新的5个Delta文件以了解近期动态并在我询问历史决策时再按需查找特定时期的Delta。”策略2定期归档与摘要可以每月或每季度人工或借助AI生成一个“季度总结Delta”概括这一阶段的主要技术方向和决策。然后将详细的旧Delta文件移入deltas/archive/子目录。在新会话中优先读取“季度总结”和近期Delta。策略3基于向量的智能检索高级这与LCP“无需向量库”的哲学略有背离但可以作为补充。你可以维护一个所有Delta内容的向量索引。当AI需要了解某方面如“认证”的历史时你可以先通过向量检索找到最相关的几个Delta再让AI读取这几个文件。这实现了精准的上下文加载。7.5 问题如何衡量LCP带来的价值解决可以从以下几个软性指标感受其价值新成员/新AI上手速度他们能否在更短的时间内提出符合项目背景的、高质量的问题和建议决策质量关于技术方案的讨论是否更多地回归到Global原则和过往决策逻辑Delta上减少了重复争论上下文切换成本你自己隔一周或一个月再回看项目是否需要更少的时间“重新加载”记忆AI建议的相关性AI助手提出的建议是否更少出现那些明显违背项目原则或重复历史失败路径的“馊主意”我个人最深刻的体会是LCP像是一个强制性的“项目记忆外置化”工具。它把原本存在于团队成员脑中、聊天记录里、过期文档里的碎片化知识结构化了、持久化了、可分享了。它可能不会让你立刻快10倍但它会让你的项目在长达数月甚至数年的生命周期中保持认知的一致性和决策的连贯性。尤其是在人员流动、使用多个AI助手协作的场景下这种“集体记忆”的价值会愈发凸显。