Archcore插件：为AI编码助手构建Git驱动的项目上下文层

1. 项目概述：为你的AI编码伙伴装上“项目记忆”

如果你和我一样，已经深度依赖Claude Code、Cursor这类AI编码助手来加速日常开发，那你一定也遇到过这个令人头疼的“失忆症”问题：昨天刚和AI一起敲定的项目架构决策，今天它又忘了；上周才建立的代码规范，这周它写新模块时又给你整出一套新花样。你不得不一遍又一遍地在聊天框里重复那些“老规矩”，仿佛在训练一个永远记不住事的实习生。

这正是Archcore Plugin要解决的核心痛点。它不是一个简单的聊天记忆插件，也不是一个让你手动维护庞大提示词库的工具。Archcore的定位非常精准：它是一个Git驱动的、面向代码库的“项目上下文层”。简单来说，它把你的项目架构、团队规则、历史决策这些“项目真理”，变成AI能自动理解、并在每次请求中自动应用的“常识”。

想象一下，你的代码库通过Git进行版本控制，通过CI/CD进行自动化部署，而Archcore则负责让AI“理解”这个代码库。它将这些知识固化为一套类型化、可验证、且具备关联关系的Markdown文档，存放在项目根目录的.archcore/文件夹里。从此，你的AI助手不再是每次对话都从零开始的“新人”，而是一个深刻理解你项目脉络、尊重团队既有决策的“资深成员”。

2. 核心理念与设计哲学：为什么是“上下文层”而非“记忆体”？

在深入技术细节前，理解Archcore的设计哲学至关重要。市面上已有不少“AI记忆”类工具，如claude-mem、Mem0等，它们主要解决的是“会话连续性”问题，即记住你和AI在聊天中讨论过什么。Archcore瞄准的是一个更底层、更持久的问题：项目本身的、与代码共生的、结构化的知识。

2.1 从“部落知识”到“一等公民工件”

在传统开发中，项目知识往往是“部落知识”——存在于资深成员的脑子里、散落在过时的Confluence页面里、或者埋没在浩如烟海的Slack历史消息中。新成员（包括AI）需要花费大量时间才能获取这些上下文。

Archcore的理念是，上下文应该成为与代码同等重要的一等公民工件。它应该是：

• 类型化的：明确区分这是架构决策（ADR）、产品需求（PRD）还是编码规范（Rule）。
• 可验证的：文档结构、必填字段、关联关系可以通过工具自动检查。
• 关联感知的：一个ADR可以关联到多个Spec，一个Spec可以衍生出多个Plan，形成一张知识图谱。
• Git托管的：和代码一起提交、评审、追溯历史，知识演进与代码演进同步。

2.2 以意图驱动，而非原始工具访问

另一个关键设计是“技能”（Skills）系统。Archcore没有简单地暴露一堆创建文档的底层MCP工具让你去记，而是提供了基于意图的高级命令。

例如，当你想记录一个已敲定的技术选型时，你不会去思考“我应该用mcp__archcore__create_document工具，并传入type=adr参数”。你只需要输入/archcore:decide，然后告诉AI“我们决定用PostgreSQL替代MongoDB作为主数据库”。AI会理解你的意图，自动选择ADR（架构决策记录）文档类型，引导你填写决策背景、已考虑的方案、决策结果及后果，并在完成后询问你是否需要基于此决策创建一条编码规则（Rule）或操作指南（Guide）。

这种设计极大地降低了使用门槛。你不需要成为Archcore的专家，你只需要用自然语言描述你想做什么，剩下的路由、模板填充、关系建立，都由技能系统来搞定。

2.3 强制执行的质量护栏

为了保证.archcore/目录下知识库的质量和一致性，Archcore插件内置了严格的“护栏”机制。最核心的一条是“MCP唯一原则”：所有对.archcore/的读写操作，必须通过Archcore提供的MCP工具进行，禁止AI直接读写文件。

这么做的原因有三：

1. 确保验证：每次创建或更新文档，都会经过archcore validate的校验，确保必填字段完整、关联ID有效、文档结构合规。
2. 自动同步：通过MCP工具写入时，会同步更新一个中心化的索引文件（通常是.archcore/_index.json），使得AI在会话开始时能快速加载整个知识图谱，而无需遍历所有文件。
3. 防止污染：直接的文件写入可能绕过所有规则，产生格式错误、破坏关联关系，导致整个上下文层失效。MCP通道是唯一的、受控的入口。

3. 核心组件深度解析：技能、类型与工作流

Archcore的强大，源于其精心设计的一套“技能-类型-工作流”体系。理解这三者的关系，是高效使用它的关键。

3.1 技能：你的高级命令集

技能是用户与Archcore交互的主要界面。目前提供了9个意图命令技能，每个都对应一个高频操作场景：

实操心得：从/archcore:decide和/archcore:standard开始对于新手，我最推荐从这两个技能入手。/archcore:decide能快速将一次技术讨论会的结果固化下来，避免日后扯皮。而/archcore:standard则是将好的实践制度化的利器。例如，团队约定“所有REST API响应必须包裹在{data: ..., error: ...}的结构中”，就可以通过这个技能，先创建一个ADR说明为什么这么定，再创建一个Rule明确规范，最后创建一个Guide教新人如何实现。

3.2 文档类型：知识的分类学

技能背后，是17种精心定义的文档类型，它们构成了项目知识的分类体系。我把它们分为三大类：

1. 愿景类：描述项目的“为什么”和“做什么”。从轻量级的idea（灵感）到重量级的、符合ISO 29148标准的brs（业务需求规格）、srs（软件需求规格）等。对于大多数敏捷团队，prd（产品需求文档）和idea是最常用的。

2. 知识类：描述项目的“是什么”和“怎么做”。这是Archcore的核心：

• adr：架构决策记录。记录某个重要技术决策的上下文、权衡和结果。
• spec：技术规格说明。定义模块、组件、API的详细契约。
• rule：团队规则。必须遵守的编码规范、流程规定。
• guide：操作指南。一步步教你怎么做的教程。
• doc：参考资料。如术语表、配置项说明等。

3. 经验类：捕获可复用的模式。

• task-type：任务模式。定义一类重复性任务的标准工作流（如“新建一个CRUD API端点”）。
• cpat：代码模式。展示一段代码“改造前”和“改造后”的对比，用于推广最佳实践或重构模式。

注意事项：关于“隐藏”的类型你可能注意到，有7个类型（如mrd,brd,urd,brs,strs,syrs,srs）不会出现在命令自动补全中。这是有意为之，旨在减少认知负荷。这些类型通常用于非常正式或特定领域的流程（如ISO标准合规）。当你需要时，可以通过/archcore:sources-track或/archcore:iso-track这类工作流来间接使用它们，或者直接调用底层的MCP工具。对于90%的日常开发，前10种类型已经足够。

3.3 工作流：多文档的编排引擎

工作流是Archcore最强大的特性之一。它不是一个简单的文档模板，而是一个有状态的、多步骤的编排引擎，能引导AI和你完成一个复杂的、涉及多种文档类型的创作过程。

以最常用的product-track为例：

1. 触发：你输入/archcore:product-track。
2. 步骤1 - Idea：AI会先引导你创建一个idea文档，快速勾勒产品概念的雏形。
3. 步骤2 - PRD：基于idea，AI会建议并帮助你创建一份更详细的prd（产品需求文档）。此时，系统会自动在PRD和之前的Idea之间建立“衍生自”的关系。
4. 步骤3 - Plan：最后，基于PRD，AI会协助制定具体的实施plan。同样，“实现”关系会被自动建立。

这个过程结束后，你得到的不再是三个孤立的文档，而是一个有清晰脉络的知识链：Idea -> PRD -> Plan。未来任何成员（或AI）查看Plan时，都能一键追溯回最初的PRD和Idea，理解完整的上下文。

其他核心工作流：

• architecture-track：非常适合技术架构演进。从记录一个架构决策（ADR）开始，到制定具体的技术规格（Spec），最后形成实施计划（Plan）。
• standard-track：团队流程标准化的利器。先通过ADR说明为什么要建立某个标准，然后制定必须遵守的规则（Rule），最后提供详细的实施指南（Guide）。

4. 完整实操指南：从零搭建你的项目知识库

理论说再多，不如动手做一遍。下面我将以一个典型的后端服务项目为例，带你完整走一遍Archcore的初始化、知识捕获和日常使用流程。

4.1 环境准备与插件安装

首先，确保你使用的是支持Archcore的AI编码环境。目前主力支持是Claude Code和Cursor。

在Claude Code中安装：

1. 打开Claude Code，在聊天框中输入：/plugin marketplace add archcore-ai/archcore-plugin
2. 等待市场列表刷新，找到Archcore插件，输入：/plugin install archcore@archcore-plugins
3. 安装成功后，重启Claude Code会话。

在Cursor中安装（需要Cursor 2.5+）：由于Archcore可能还未上架官方市场，需要通过GitHub仓库直接安装。

1. 打开Cursor，新建一个Agent聊天窗口。
2. 在输入框中完整键入以下命令（注意：/add-plugin可能没有自动补全）：/add-plugin archcore@https://github.com/archcore-ai/archcore-plugin
3. 回车执行，等待安装完成。

安装完成后，打开你的项目根目录。如果这是首次安装，插件会启动一个“启动器”，自动下载Archcore CLI并缓存。你会在项目根目录下看到一个新建的.archcore/文件夹（如果不存在的话，AI会在第一次操作时创建）。

4.2 第一步：知识库初始化与探索

不要一上来就想着创建大量文档。先从探索和轻量级捕获开始。

操作1：快速盘点现有上下文在AI聊天框中输入：/archcore:statusAI会运行并返回一个仪表盘，显示当前.archcore/目录下的文档统计。如果是新项目，这里通常是空的。这个命令让你对知识库的现状有个底。

操作2：引导式知识捕获假设你的项目里已经有一个关于“用户认证”的模糊设计，散落在代码注释或你的脑子里。输入：/archcore:captureAI会问你：“你想要捕获什么？一个模块、一个组件、一个API端点，还是其他什么？” 你回答：“我们之前讨论过的用户认证模块的设计。” AI会判断这是一个技术规格，并引导你创建一份spec文档。它会问你一系列结构化的问题，比如：

• 模块的名称和目的？
• 核心接口和数据结构？
• 依赖的其他模块？
• 非功能性要求（性能、安全）？

你只需要像聊天一样回答，AI会帮你整理成格式规范的Markdown文档，并保存到.archcore/specs/目录下。关键点：即使你回答得很零散，AI也会基于它对spec文档类型的理解，帮你组织出清晰的章节。

4.3 第二步：固化关键架构决策

项目里总有一些“历史遗留”的重大决策，需要让所有人（包括未来的AI）铭记。

操作：记录一个技术选型决策输入：/archcore:decideAI会响应：“好的，让我们记录一个架构决策。这个决策是关于什么的？” 你回答：“关于为什么我们选择使用PostgreSQL而不是MongoDB作为主数据库。” 接下来，AI会引导你填写ADR的核心部分：

• 背景：当时面临什么问题？（需要支持复杂查询和事务）
• 考虑的方案：评估了哪些选项？（MongoDB的灵活性 vs PostgreSQL的ACID特性和SQL生态）
• 决策：我们选择了什么？（PostgreSQL）
• 后果：这个决策带来了什么影响？（需要更早设计表结构，但获得了强一致性和丰富的连接查询能力）

填写完成后，AI不仅会保存ADR，还会贴心地问：“需要基于这个决策创建一条团队规则（Rule）或操作指南（Guide）吗？” 如果你回答“是”，它会无缝衔接到创建Rule或Guide的流程，例如创建一条Rule：“所有新的数据存储需求，应优先评估PostgreSQL，如无特殊理由，默认使用PostgreSQL。”

4.4 第三步：建立团队开发规范

当团队在某个实践上达成一致后，就用/archcore:standard把它固化下来。

操作：建立API响应格式标准输入：/archcore:standardAI：“你想要建立什么团队标准？” 你回答：“统一所有REST API的响应格式。” 随后，Archcore的standard-track工作流启动：

1. ADR阶段：AI帮你创建一份ADR，阐述统一格式的好处（前端处理方便、错误信息标准化、易于监控等）。
2. Rule阶段：基于ADR，创建一条强制性的Rule。内容会类似：“所有REST API端点必须返回{success: boolean, data: any, error: {code: string, message: string}}格式的JSON对象。success为true时error为null，为false时data为null。”
3. Guide阶段：最后，创建一个Step-by-Step的Guide，教开发者如何在不同的框架（如Express.js, Spring Boot）中实现这个规则，并附上代码示例。

至此，一个完整的标准就建立了。未来任何AI在编写新的API控制器时，都会自动引用这条Rule，确保格式一致。

4.5 第四步：规划与执行新功能

当需要开发一个新功能时，利用工作流来管理从想法到计划的整个过程。

操作：规划“用户通知中心”功能输入：/archcore:product-trackAI启动产品工作流：

1. Idea：先快速记录“用户通知中心”的初步想法：支持站内信、邮件、推送；区分系统通知和用户间消息等。
2. PRD：基于Idea，展开详细的PRD。AI会引导你定义用户故事、功能列表、成功指标（如“99%的消息在1秒内投递”）。
3. Plan：最后，制定技术实施计划。AI会建议拆分子任务（设计消息表、实现发送队列、开发前端组件），并估算复杂度。

完成后，.archcore/目录下会新增三个互相关联的文档。当你后续让AI“实现通知中心的发送队列”时，它可以直接查阅这份Plan和背后的PRD，准确理解任务范围和验收标准。

5. 高级技巧与避坑指南

在实际使用Archcore几个月后，我积累了一些能极大提升效率的技巧，也踩过一些坑，在这里分享给你。

5.1 技巧一：善用“关系”，构建知识图谱

Archcore文档间的“关系”是其灵魂。创建文档时，务必花点时间建立正确的关系。常见关系有：

• derived-from：这份文档源自哪份文档？（如Plan derived-from PRD）
• implements：这份文档实现了哪个设计？（如Spec implements ADR）
• related-to：这份文档与哪些其他文档相关？（如一个关于“缓存”的Guide可能related-to多个使用缓存的Spec）
• supersedes：这份文档取代了哪个旧文档？（用于文档版本迭代）

如何操作：在AI引导创建文档的最后阶段，它通常会问：“这份文档与现有的哪些文档相关？” 这时不要跳过。你可以让AI基于内容推荐，也可以手动指定文档ID。建立好的关系，可以通过/archcore:graph命令可视化，一目了然。

5.2 技巧二：定期进行“健康审查”

知识库和代码一样，也会“腐化”。过时的决策、无人维护的规范、与代码脱节的Spec，都会误导AI。建议每周或每轮迭代后，运行一次：/archcore:review这个命令会进行全面的健康扫描，报告：

• 孤儿文档：没有任何入站或出站关系的文档，可能已失效。
• 陈旧状态：标记为draft或proposed但很久没更新的文档。
• 关联断裂：声明了关系，但目标文档不存在的链接。
• 命名不一致：同类文档的命名风格不统一。

根据报告，你可以用/archcore:actualize来更新或归档文档，保持知识库的清洁。

5.3 技巧三：为复杂模块创建“任务模式”

如果你发现团队经常重复某一类开发任务（比如“新建一个GraphQL Resolver”、“为实体添加审计日志”），不要每次都从头解释。使用/archcore:capture，选择创建task-type文档。

一个task-type文档就像一个标准作业程序，它定义了：

• 触发条件：什么时候用这个模式？（如“当需要新增一个查询或变更端点时”）
• 输入：需要哪些信息？（如“模块名、字段定义、权限要求”）
• 步骤：标准步骤是什么？（1. 在schema.graphql中定义类型和字段 2. 在resolvers/下创建文件 3. 实现resolve函数 4. 添加单元测试...）
• 输出：交付物是什么？（如“可工作的Resolver、更新的Schema、通过的测试”）

创建好后，下次你只需要说“按‘新建GraphQL Resolver’的任务模式，给我创建一个用户查询的resolver”，AI就会自动套用这个模式，极大提升效率。

5.4 常见问题与排查

问题1：AI好像没读取到我的Archcore规则？

• 检查1：确认插件已正确安装并在当前项目激活。在Claude Code中，输入/plugin list查看。
• 检查2：确认会话开始时AI加载了上下文。每次新建会话，插件都会自动运行archcore mcp加载索引。你可以观察启动日志或尝试/archcore:status看是否有输出。
• 检查3：规则文件本身是否有效？在项目根目录运行archcore validate（如果CLI已全局安装）检查.archcore/目录下所有文档的合法性。

问题2：我想修改一个Archcore文档，但AI总是阻止我直接编辑文件。这是设计如此，是“MCP唯一原则”在起作用。正确的做法是：告诉AI“我想更新文档 [文档ID] 的某个部分”，然后通过对话让AI使用MCP工具来完成更新。这确保了所有修改都经过验证和索引更新。如果你确实需要直接编辑（比如批量重构），可以临时在对话中说明“请暂时允许我直接编辑这个文件以进行批量修改”，但完成后最好运行一下archcore validate。

问题3：团队协作时，如何保证大家写的Archcore文档风格一致？Archcore本身通过严格的文档类型模板来保证结构一致。但对于内容风格，建议团队在初期共同创建几条“元规则”。例如，使用/archcore:standard建立一条关于“如何书写ADR”的Rule，规定ADR的背景部分必须包含业务场景和技术上下文，考虑的方案至少要有两个对比等。将这些写作规范也纳入Archcore管理，让AI在协助创作时就能遵循。

问题4：.archcore/目录应该提交到Git吗？绝对应该！这是Archcore设计的核心优势之一。将.archcore/视为与src/同等重要的源代码。它的版本历史记录了项目决策和架构的演进过程。在Code Review时，不仅要Review代码变更，也要Review相关的Archcore文档变更，确保决策和实现同步更新。

6. 与现有开发流程的融合

引入Archcore不是要颠覆你现有的敏捷或工程实践，而是增强它们。

与Git工作流结合：为Archcore文档创建PR模板。例如，要求任何涉及架构变动的PR，必须关联一个ADR文档；任何新功能PR，必须关联一个Plan文档。在CI流水线中，可以加入archcore validate步骤，确保提交的文档都是有效的。

与项目管理工具结合：你可以将Archcore文档的ID（如adr-002-postgresql-choice）链接到Jira、Linear等工具的任务卡片上。这样，任务上下文不仅仅是标题和描述，而是直接链接到结构化的项目知识。

与团队 onboarding 结合：新成员加入后，不要直接扔给他代码。让他先运行/archcore:review和/archcore:graph，快速了解项目的关键决策、核心规范和模块关系。然后让他通过/archcore:plan为一个简单功能做规划，在实践中学习如何使用这套知识体系。

Archcore Plugin带来的改变是潜移默化但深刻的。它最初可能只是帮你省去一些重复的提示，但随着项目知识库的不断丰富，你会发现AI助手变得越来越“懂行”，它提出的方案越来越贴合项目实际，它犯的“低级错误”越来越少。这本质上是在将团队的集体智慧和项目的历史脉络，以一种机器可读、可推理的方式固化下来，让AI真正成为一个可持续、可进化的项目成员，而不是一个每次对话都需要重新培训的临时工。