1. 项目概述为你的AI编码伙伴装上“项目记忆”如果你和我一样已经深度依赖像Claude Code或Cursor这类AI编码助手来加速日常开发那你肯定也遇到过那个让人头疼的瞬间你明明上周才和它详细讨论过项目的架构决策比如“所有API处理器必须放在src/api/handlers/目录下”但今天让它新建一个用户认证接口时它又把文件生成到了src/routes/里。或者团队已经通过ADR架构决策记录正式决定采用PostgreSQL而非MongoDB但AI在为新模块设计数据层时又开始“重新思考”数据库选型问题。这种“失忆”现象的根本原因在于我们传递给AI的“上下文”是短暂且碎片化的。它可能存在于某次对话的历史记录里藏在某个被遗忘的.cursorrules文件角落或者分散在团队成员各自维护的CLAUDE.md中。这些信息没有版本化难以共享更无法在AI跨会话、跨任务时被稳定地继承和理解。Archcore Plugin就是为了解决这个核心痛点而生的。它不是另一个聊天记忆增强工具也不是一个一次性的代码生成器。你可以把它理解为你代码仓库的“AI可读型架构层”。它通过一套基于Git的、类型化的文档系统.archcore/目录将项目的架构、规则、决策固化下来并确保你的AI助手在每一次交互中都能自动加载并遵循这些上下文。简单来说Git管理你的代码版本CI/CD负责交付而Archcore负责让你的AI真正理解你的项目。2. 核心设计理念从临时提示到持久化知识库在深入实操之前理解Archcore背后的设计哲学至关重要。这决定了你是否能把它用对地方发挥最大价值。2.1 核心理念上下文即工件传统上我们通过长篇的提示词prompt或配置文件来指导AI。这种方式有几个固有缺陷难以维护随着项目演进提示词文件会变得臃肿、矛盾且更新不同步。缺乏结构AI很难从一段自由文本中精确提取“决策”、“规则”和“架构”等不同类别的信息。无法关联一个关于“认证服务”的决策如何与相关的API规范、数据库Schema变更关联起来在纯文本提示中这种关系是隐式的AI无法主动利用。Archcore提出了一个根本性的转变将项目上下文视为与源代码同等重要的一等公民First-class Artifact。这意味着类型化上下文被明确分类为ADR架构决策记录、Rule规则、Spec规范、Guide指南等17种具体文档类型。每种类型有固定的结构和预期内容。版本化所有.archcore/下的文档都存储在Git中与代码一起接受版本控制、代码评审和合并。关系化文档之间可以建立明确的链接关系例如一个adr文档可以决定一个spec而该spec又实现了一个prd。这形成了一个可查询、可追溯的知识图谱。机器可读通过标准的MCP模型上下文协议暴露给AIAI能像调用函数一样精准地查询、创建和更新这些上下文文档。2.2 与同类工具的定位差异市面上已有不少提升AI开发体验的工具但Archcore解决的是一个更底层、更持久的问题。我们可以通过一个对比表格来清晰定位工具类别代表工具核心目标Archcore的差异点方法论框架BMAD, Superpowers, Spec Kit定义AI代理的开发流程、角色和阶段。例如Spec Kit是“需求说明书 - 计划 - 实现”的一次性工作流。提供持久化知识。方法论告诉你“怎么做”Archcore提供“做什么”和“为什么这么做”的持久化记录。Archcore存储的是项目演进的“事实”而非单次任务的“流程”。会话记忆claude-mem, Mem0, agentmemory跨会话记住用户与AI的对话历史、代码片段实现长期对话连续性。存储项目真相。记忆工具记住“我们说过什么”Archcore存储“这个项目本身是什么样、应该怎样”。它是关于项目的规范知识而非对话历史。文档模板Cline Memory Bank提供一套固定的Markdown模板如projectbrief.md,systemPatterns.md来记录项目信息。类型化与关系化。Archcore提供了更丰富的文档类型和强制性的关系链接并且通过MCP工具进行强验证确保文档质量与一致性而不仅仅是文件模板。选择建议如果你需要为AI代理设计一套复杂的、多步骤的工作流应该选择方法论框架。如果你希望AI能记住跨会话的对话内容应该选择会话记忆工具。而当你受够了不断向AI重复解释项目特有的规则、架构和决策希望这些知识能一劳永逸地被所有AI工具Claude Code, Cursor等理解并遵守时Archcore就是为你准备的。3. 快速上手指南安装与初体验理论说再多不如动手试。Archcore Plugin的安装非常轻量几乎没有任何前置依赖。3.1 安装步骤对于Claude Code用户在Claude Code的聊天窗口中直接输入以下命令/plugin marketplace add archcore-ai/archcore-plugin /plugin install archcorearchcore-plugins第一条命令将Archcore的插件市场源添加到你的Claude Code中第二条命令进行安装。安装后插件会自动在后续的会话中生效。对于Cursor用户要求Cursor 2.5版本由于Archcore尚未上架官方市场需要从GitHub直接安装。打开Cursor的一个新的Agent聊天窗口输入/add-plugin archcorehttps://github.com/archcore-ai/archcore-plugin请注意/add-plugin命令可能不会出现在自动补全中需要手动完整输入。安装后可能需要重启Cursor或新建一个Agent会话来激活插件。提示插件内部捆绑了一个启动器launcher它会在首次使用时自动下载并缓存Archcore CLI工具。如果你已经在系统全局安装了archcore命令行工具例如通过curl -fsSL https://archcore.ai/install.sh | bash插件会优先使用你系统PATH中的版本避免冲突。3.2 三个必试的启动提示安装完成后在你项目的根目录打开AI对话窗口尝试下面三个提示它们能帮你快速建立对Archcore能力的直观感受“展示这个仓库已有的上下文。”AI会扫描你的项目根目录下的.archcore/文件夹如果存在并总结其中已定义的决策、规则和规范。如果你的项目是全新的没有这个目录AI通常会建议你从现有的文档如README、ADR文件开始引导式地创建初始上下文。“创建一条规则API处理器必须放在src/api/handlers/目录下。”这是一个创建rule类型文档的请求。AI会引导你完成规则的创建输入规则标题、详细描述、 rationale制定原因并可能建议相关的标签。创建完成后这条规则就被记录在.archcore/rules/目录下的一个Markdown文件中。此后当你要求AI创建新的API处理器时它会自动引用这条规则将文件生成到正确的位置无需你再额外提醒。“记录一个我们选择PostgreSQL而非MongoDB的ADR然后告诉我这个决策会影响哪些未来的工作。”这个请求会触发一个多步流程。首先AI会帮你创建一个adr文档记录数据库选型的背景、权衡和最终决定。接着AI会利用Archcore的关系图谱功能分析这个新的ADR并建议可能需要创建或更新的关联文档。例如它可能会提示“这个ADR可能影响数据访问层的spec建议创建一条关于数据库连接池配置的rule或者更新现有的数据迁移guide。” 这展示了Archcore如何将孤立的决策与未来的开发任务主动关联起来。如果以上任何一个演示让你觉得“这正是我需要的”那么Archcore的其余部分对你来说就是更结构化、更强大的同类能力扩展。4. 核心组件深度解析技能、文档与工作流Archcore的强大之处在于它提供了一套完整的“语言”和“工作流”来管理项目知识。这套体系主要由技能、文档类型和轨道构成。4.1 技能面向意图的交互接口技能是用户与Archcore系统交互的主要方式。你不需要记住复杂的文档类型或文件路径只需描述你的意图对应的技能就会接管后续所有工作。目前共有9种核心意图命令技能技能命令意图典型使用场景/archcore:capture捕获“把我们现在讨论的这个用户认证模块的设计记录下来。” AI会判断这是该记成spec技术规范还是adr决策并引导你完成。/archcore:plan规划“为‘消息推送功能’制定一个实施计划。” 这会启动一个规划流程可能产出prd产品需求文档和详细的plan实施计划。/archcore:decide决策“我们决定在后端服务中统一使用UUID作为主键。” 明确创建一个adr并可能后续关联到rule和guide。/archcore:standard标准化“我们要建立代码评审的标准流程。” 这会启动standard-track系统化地产生决策、规则和操作指南。/archcore:review审查“检查一下我们项目的文档健康度。” AI会分析.archcore/目录报告缺失的关联、过时的文档、命名不一致等问题。/archcore:status状态“我们有多少个待决定的RFC有多少个已过时的规范” 提供一个项目上下文状态的仪表板视图。/archcore:actualize更新“找出那些因为代码变更而变得陈旧的文档。” 通过静态分析对比代码和文档发现不一致之处。/archcore:graph图谱“可视化展示所有决策和规范之间的关系。” 生成一个Mermaid格式的关系图帮助理解知识脉络。/archcore:help帮助“Archcore都能做什么” 列出所有可用的技能、文档类型和工作流。实操心得刚开始使用时最常用的是/archcore:capture和/archcore:decide。养成习惯每当在讨论中形成一个明确结论或设计时就立刻用这两个命令之一记录下来。/archcore:review和/archcore:actualize则适合在迭代周期结束时运行作为文档“健康检查”确保知识库与代码同步。4.2 文档类型结构化的知识单元技能背后对应的是17种具体的文档类型它们是知识的载体。每种类型都有预定义的结构标题、状态、标签、关系、正文章节确保信息以一致、可解析的方式存储。我将它们分为三大类以便理解1. 愿景与需求类这类文档描述“做什么”和“为什么做”。prd(产品需求文档): 定义产品目标、范围、成功指标。idea/mrd(市场需求文档) /brd(业务需求文档) /urd(用户需求文档): 用于早期探索和市场分析。brs/strs/syrs/srs: 这是一套符合ISO 29148标准的正式需求规范层级从业务需求一直分解到系统需求适用于对合规性和追溯性要求高的项目。2. 知识与决策类这类文档描述“怎么做”和“为什么这么做”。adr(架构决策记录):最核心的类型。记录一项重要的技术决策包含上下文、权衡方案、决策结果及后果。rfc(征求意见稿): 用于在团队内提案并收集反馈尚未形成最终决策。rule(规则): 团队必须遵守的标准如“所有API响应必须包裹在{data, code, message}结构中”。guide(指南): 具体的操作指南如“如何配置本地开发环境”。spec(规范): 技术组件或系统的详细契约如“用户服务API接口规范”。doc(文档): 参考材料如术语表、项目目录结构说明。3. 经验与模式类这类文档捕获“最佳实践”。task-type(任务类型): 定义一类重复性任务的标准工作流如“新建一个CRUD模块”的标准步骤。cpat(代码模式): 记录前后代码的对比模式例如“从使用var改为使用let/const的最佳实践示例”。注意事项并非所有类型都需要你手动调用。像/archcore:plan这样的意图技能会根据场景自动选择并组合合适的文档类型。对于mrd,brs等较为小众的类型它们主要被更高级的“轨道”工作流所使用不会出现在命令自动补全里以减少干扰但你仍然可以通过底层MCP工具直接创建。4.3 轨道预设的多文档工作流轨道是将多个文档类型按逻辑顺序串联起来的预设工作流。它解决了“先写哪个后写哪个它们之间如何关联”的问题特别适合中大型、结构化的开发任务。轨道流程适用场景product-trackidea→prd→plan轻量级产品功能开发。从一个想法开始形成产品需求再制定实施计划。快速且直接。architecture-trackadr→spec→plan技术架构驱动开发。先做出关键架构决策基于决策编写技术规范最后形成开发计划。standard-trackadr→rule→guide建立团队标准。先决策为什么要有这个标准再制定规则标准是什么最后提供指南如何遵守。feature-trackprd→spec→plan→task-type完整功能开发生命周期。从产品需求到技术规范到开发计划最后沉淀出可复用的任务模式。sources-trackmrd→brd→urd深度市场与用户调研。依次分析市场、业务和用户需求为产品定义提供扎实依据。iso-trackbrs→strs→syrs→srs严格的需求追溯。遵循ISO 29148标准层层分解需求适用于医疗、金融等强监管领域。使用轨道的价值当你启动一个轨道时AI不仅会帮你创建当前步骤的文档还会自动为你建立与上一步文档的“关系”链接。例如在architecture-track中spec文档会自动链接到它所实现的adr。这种自动化的关系管理使得后续的追溯、影响分析/archcore:review变得可能且准确。5. 实战演练从零构建一个微服务的上下文层让我们通过一个具体的例子看看如何在实际项目中应用Archcore。假设我们正在启动一个名为“UserHub”的新微服务负责用户管理和认证。5.1 初始化与首次捕获首先在UserHub项目根目录打开Claude Code或Cursor的AI对话。探索现有上下文输入“展示这个仓库已有的上下文。”由于是新项目AI会报告.archcore/目录为空并建议进行初始化。制定首个架构决策我们决定使用JWT进行无状态认证。输入“记录一个ADR在UserHub服务中使用JWT进行无状态认证。”AI会启动/archcore:decide技能引导你填写ADR内容。背景需要一种安全、可扩展的认证机制支持多客户端。权衡方案对比Session-Cookie、OAuth 2.0、JWT。JWT在无状态、自包含和易于跨域方面有优势但需妥善处理令牌注销问题。决策采用JWT。Access Token有效期设为15分钟Refresh Token有效期设为7天通过Redis黑名单处理注销。后果所有客户端需适配JWT的携带方式通常放在Authorization头需要实现令牌刷新端点需要引入Redis依赖。确认后AI会在.archcore/adrs/下生成一个类似2024-05-27_use-jwt-for-stateless-auth.md的文件。5.2 将决策转化为团队规则有了ADR我们需要将其转化为团队必须遵守的具体规则。创建规则输入“基于JWT的ADR创建一条关于API认证的规则。”AI可能会建议使用/archcore:standard技能或者直接引导创建rule。规则标题API请求必须使用JWT进行认证内容详细描述JWT的格式HS256算法、存放位置Authorization: Bearer token、公开接口的白名单等。关联AI会自动将此规则与上一步创建的JWT ADR建立“由...决定”的关系。创建操作指南接着输入“为前端如何集成JWT认证写一个指南。”AI会创建guide文档步骤可能包括如何登录获取token、如何将token存入localStorage或cookie、如何在请求头中注入、如何处理token过期和自动刷新。同样这份指南会自动关联到之前的rule和adr。至此我们通过standard-track决策→规则→指南完成了一个完整标准的建立。5.3 规划一个新功能用户个人资料更新现在产品提出要增加用户个人资料头像、昵称更新功能。启动产品轨道输入“为‘用户个人资料更新功能’启动一个产品规划。”AI会启动/archcore:product-track。第一步创建prd。AI会引导你定义功能目标允许用户修改个人信息、范围头像上传、昵称、个人简介、成功指标用户资料完善率提升X%。第二步基于prd创建spec。AI会参考已有的JWT认证规则开始编写技术规范定义PATCH /api/v1/users/me接口的请求/响应格式、头像上传的OSS存储策略、昵称敏感词过滤规则等。在编写过程中AI会自动引用相关的adr和rule。第三步基于spec创建plan。AI会拆解开发任务后端API开发、前端表单页面、图片上传组件集成、测试用例编写等。在整个过程中AI的上下文始终包含了我们之前定义的JWT认证规则。因此它在设计API规范时会自动注明“此接口需要JWT认证”在编写前端指南时会提醒“调用此API前需确保已设置Authorization头”。5.4 进行健康度审查功能开发一段时间后我们可以运行一次审查。 输入“审查一下我们项目的文档健康度。” AI会运行/archcore:review技能并可能报告✅ 关联良好JWT ADR关联了规则和指南。⚠️ 孤儿文档发现一个早期创建的关于“数据库连接池配置”的guide没有关联到任何adr或spec。建议关联或评估是否仍需保留。⚠️ 命名不一致有的文档使用“User”有的使用“user”建议统一。 代码漂移检测通过/archcore:actualize发现代码中已经实现了Refresh Token的Redis黑名单机制但对应的guide文档还未更新标记为“过时”。这个审查报告就像一次项目的“架构体检”帮助我们持续维护上下文层的质量和有效性。6. 高级配置与集成考量对于团队协作、企业环境或特定工作流Archcore也提供了灵活的配置选项。6.1 团队部署与离线环境团队部署Cursor 团队负责人可以在Cursor的Dashboard → Settings → Plugins → Team Marketplaces中通过“Import”添加Archcore插件的GitHub URL。这样团队所有成员在安装插件时都能直接从团队市场看到并安装统一版本。离线环境/自带CLI 如果公司网络策略限制或你已通过其他方式如go install安装了Archcore CLI插件也支持。确保archcore命令在系统的PATH环境变量中。插件启动器会优先使用PATH中的全局版本。如果需要完全禁用自动下载可以设置环境变量ARCHCORE_SKIP_DOWNLOAD1。或者通过ARCHCORE_BIN/abs/path/to/archcore环境变量指定CLI的绝对路径。6.2 守卫机制MCP唯一写入原则这是Archcore一个关键的设计它保证了知识库的完整性和一致性。插件启用了“MCP-only”守卫。原理所有对.archcore/目录的创建、修改、删除操作都必须通过Archcore提供的MCP工具如mcp__archcore__create_document来完成。拦截插件会拦截AI代理试图直接写入.archcore/文件的原始指令并引导其使用正确的MCP工具。好处验证在写入前MCP工具会校验文档结构必填字段、类型格式和关系链接的有效性。模板化确保生成的Markdown文件符合标准模板便于机器和人类阅读。同步更新索引每次变更后会自动更新内部的文档索引和关系图保证后续查询的实时性。这意味着你无法通过简单的“请创建一个名为xxx.md的文件”来向.archcore/添加内容。你必须通过/archcore:decide、/archcore:capture等技能或直接调用底层的MCP工具。这虽然增加了一点约束但从根本上防止了随意、无效的文档污染知识库。6.3 与现有工作流的融合你可能会担心引入Archcore是否会与现有的CLAUDE.md或.cursorrules冲突。互补而非替代Archcore专注于结构化、持久化、可关联的项目知识。而CLAUDE.md更适合存放一次性的、会话相关的提示或者项目非常早期的、尚未结构化的想法。两者可以共存。迁移策略一个好的启动方式是运行/archcore:review时AI可能会建议你将CLAUDE.md中一些成熟的、稳定的约定如“我们使用Prettier进行代码格式化”提取出来创建成正式的rule和guide文档。这样这些知识就从个人提示升级为了团队资产。渐进采用不需要一开始就记录所有事情。从最重要的、最常被AI“忘记”的架构决策和团队规则开始。随着时间推移逐渐将更多的 tribal knowledge部落知识沉淀到Archcore中。7. 常见问题与排查技巧实录在实际使用中你可能会遇到一些典型问题。以下是我根据经验总结的排查清单问题现象可能原因解决方案AI代理完全无视.archcore/中的规则。1. 插件未正确安装或激活。2. 会话开始时上下文加载失败。3. AI的提示词优先级设置可能覆盖了Archcore上下文。1. 检查插件安装命令是否成功尝试重启IDE或新建AI会话。2. 在会话开始时手动输入“加载Archcore上下文”或查看AI的初始回复是否提及加载了Archcore。3. 确保你没有在对话开始时使用强力的系统提示词如“忽略所有其他指令…”这可能会干扰Archcore的上下文注入。运行/archcore:命令无反应或报错。1. 命令拼写错误。2. Archcore CLI启动或连接失败。3. 项目根目录没有正确识别。1. 使用/archcore:help查看所有可用命令注意冒号是英文的。2. 查看IDE后台或终端是否有错误日志。尝试设置ARCHCORE_SKIP_DOWNLOAD1并使用全局安装的CLI。3. 确保你的AI对话是在项目根目录或子目录中打开的Archcore需要定位.archcore/文件夹。创建的文档关系没有正确显示在图中。1. 创建文档时没有明确指定或确认关系。2. 关系图渲染需要时间或缓存。3. Mermaid语法生成或渲染问题。1. 在创建adr、spec等文档时仔细完成AI引导的“关联到现有文档”步骤。2. 运行/archcore:graph命令后稍等片刻。可以尝试重新加载会话。3. 生成的Mermaid代码可以复制出来到在线Mermaid编辑器如mermaid.live中检查是否能正常渲染。团队其他成员看不到我创建的Archcore文档。文档没有提交并推送到远程Git仓库。Archcore文档就是普通的Markdown文件保存在.archcore/目录下。确保将该目录纳入版本控制通常已在.gitignore的例外中并像对待源代码一样进行git add,commit和push。其他成员拉取代码后即可看到。我想修改一个Archcore文档的模板。希望自定义文档类型的前置内容或结构。Archcore目前主要支持通过其CLI和MCP工具来维护文档结构。直接修改生成的.md文件是可行的但要注意保持其YAML Frontmatter包含类型、状态、关系等元数据的格式正确。更高级的自定义可能需要关注Archcore CLI未来的更新。独家避坑技巧启动时验证在新项目或新环境使用Archcore时第一个命令不要执行复杂的创建而是先运行/archcore:status。如果它能正确返回信息哪怕是空的说明插件、CLI和项目路径的基础链路是通的。关系先行在创建新文档时养成先思考“这个文档和哪个已有的文档相关”的习惯。主动建立关系比事后通过审查再补关联要容易得多。高质量的关系网络是Archcore价值倍增的关键。善用“审查”与“更新”将/archcore:review和/archcore:actualize作为每周或每个冲刺Sprint结束时的固定动作。这能有效防止上下文层与代码实际脱节变成又一个“过期没人看的Wiki”。从小处着手不要试图一次性把项目所有历史决策都录入Archcore。从当前迭代最重要的一个功能或最令人困惑的一个架构点开始记录1-2个ADR和规则立即体验AI行为的变化。获得正反馈后再逐步扩大范围。Archcore Plugin代表了一种思维转变将AI助手从一个需要不断重复教育的“临时工”转变为一个真正理解项目脉络、尊重团队历史的“长期伙伴”。它通过将模糊的、隐式的项目知识转化为显式的、结构化的、可编程的上下文最终让AI生成的代码更贴合你的项目让团队协作更顺畅也让宝贵的架构决策不再淹没在聊天记录里。开始尝试从记录下一个重要的技术决策做起你会发现让AI记住你的项目其实并不难。