把文档交给 AI 之前，先让知识有依赖关系：用 Manthan 把概念卡接入 Claude Code 与 MCP
团队把设计文档、故障复盘和技术规范塞进对话窗口后，常见结果是：模型能复述片段，却很难区分“先理解什么”和“后续结论依赖什么”。这不是单纯的上下文长度问题。原始文档往往同时包含定义、前提、例外和实践步骤；如果所有内容被压成一段摘要，概念之间的依赖边就丢了。
Manthan 是 SiRune 运营的知识卡片服务。它的核心不是把资料做成逐张背诵的闪卡，而是把概念组织为带 prerequisites 的卡片集合，并按“哪些概念能解锁更多后续理解”的思路展示学习路径。它同时提供 Web 界面、JSON 直导入、Claude Skill 与 Streamable HTTP MCP 服务，因而可以把整理知识这一步放进编码 Agent 的工作流。
本文聚焦一个可复现的场景：把一份内部工程规范拆成可检查、可继续维护的概念卡，再让 Claude Code 读取或补充卡组。它适合整理架构决策记录、接入指南、运行手册和陌生项目的关键约束；不适合把卡片当作安全审计或事实真实性的替代品——原始文档仍是最终依据。
为什么“依赖”比“摘要”更重要
假设你要把一份服务接入规范交给新成员或 Agent。常规摘要可能并列列出认证、幂等、重试和告警；但真实顺序通常是：先知道请求身份如何传递，才能理解权限失败；先理解幂等键的语义，才知道为何重试不能随意发生。把这些关系写出来，有两个直接收益。
第一，读者能从最小前置知识开始，而不是在一堆并列段落中猜阅读顺序。第二，Agent 在提出修改建议时，可以沿着前置概念回溯：一条“重试策略”的建议若与“幂等键”卡冲突，就应回到规范而不是直接生成补丁。
这里的关键取舍是粒度。卡片不应等同段落，也不该只留一个术语定义。官方 Skill 建议一张卡只表达一个想法，标题保持 2–6 个词，内容用 1–4 个短句；完整主题可拆成 10–40 张卡。过大时依赖图没有意义，过小时则让维护成本超过复用价值。
先用 JSON 构造一个可审阅的最小卡组
Manthan 支持直接导入 JSON。这条路径适合已经由人或 Agent 整理好的资料：服务会按给定卡片导入，而不是再消耗一次自身的 AI 生成配额。prerequisites 写的是同一批次内其他卡片的标题；没有匹配到的标题会被跳过，因此提交前最好在仓库里做一次校验。
下面是一个围绕 API 接入约束的最小例子。内容故意保持短小：它的作用是提供可导航的知识索引，不是替代完整 API 文档。
[
{
"title": "请求身份",
"content": "每个请求都必须携带可验证的调用方身份。身份决定后续的授权范围。",
"tags": ["api", "security"]
},
{
"title": "权限边界",
"content": "授权只授予完成当前操作所需的最小范围。拒绝时记录可追踪的原因。",
"tags": ["api", "security"],
"prerequisites": ["请求身份"]
},
{
"title": "幂等键",
"content": "写操作使用稳定的幂等键，重复提交不能产生额外副作用。",
"tags": ["api", "reliability"]
},
{
"title": "安全重试",
"content": "仅对可恢复错误重试，并遵守指数退避。写操作重试以前必须确认幂等语义。",
"tags": ["api", "reliability"],
"prerequisites": ["幂等键"]
}
]
将文件保存为例如 api-contract.json 后，可在 Manthan 的 Create Cards 页面拖入或粘贴。导入完成后，优先检查两件事：每张卡是否只解释了一个可判断的概念，以及每条依赖是否真的是“必须先懂”而非“相关但可选”。后者是知识图最常见的失真来源；把所有相关项都连成前置条件，会让路径退化为一条冗长链表。
让 Claude Code 使用同一份卡组
Manthan 的 MCP 服务端点是 https://api.sirune.tech/mcp，使用 Streamable HTTP。文档列出了列出卡组、列出卡片、创建卡组、添加/编辑卡片和移动卡组等工具。对 Claude Code，官方给出的连接形态如下；把令牌放进环境变量，避免把个人 API Key 写入 shell 历史或项目配置。
export MANTHAN_API_KEY="your-personal-api-key"
claude mcp add --transport http manthan https://api.sirune.tech/mcp \
--header "Authorization: Bearer ${MANTHAN_API_KEY}"
API Key 从 Manthan 账户的 Developer 区域生成，并可在同一位置撤销。接入后，比较稳妥的提示方式不是要求 Agent “凭卡片完成所有工作”，而是明确它的职责边界：先列出相关 deck 和 cards，说明准备采用的前置链，再根据卡片提出问题、补卡建议或代码变更草案。例如：
读取“API Contract”卡组；在修改重试逻辑前，先列出与“安全重试”有关的前置卡。若发现现有实现无法满足卡片约束，只报告冲突和需要确认的原始规范段落，不要自行放宽约束。
这样能把知识库当作显式约束层，而不是又一个未经检查的提示词来源。对于跨仓库团队，这也减少了每个 Agent 分别从长文中抽取不同“记忆”的概率。
把卡片维护纳入变更流程
卡组第一次导入后不应冻结。更实用的做法是把它纳入与代码相近的变更节奏：当接口契约、故障处置流程或架构决策发生变化时，提交者同时检查受影响的卡片。MCP 的 list_manthan_decks 与 list_cards_in_deck 适合先建立盘点；确认某张卡过期后，再使用 edit_manthan_card 替换标题、内容、标签或前置条件。新出现的独立约束可以用 add_manthan_card 补到既有卡组；需要将整个主题重组时，重新以 import_manthan_cards 创建一组新卡通常更清晰。
不要让 Agent 在没有审阅的情况下自动改写整张图。一个可操作的审阅循环是：先由 Agent 读取某个 deck，输出“准备新增、修改、删除的卡”和每条依赖边的理由；维护者只确认概念粒度与依赖方向；最后才执行写操作。特别是删除卡片时，要先找出哪些下游卡把它列为前置条件。否则图表外观虽然更简洁，实际却会留下无法解释的学习跳跃。
也可以把卡片作为 PR 讨论的辅助产物。例如一次服务改动引入了“异步补偿”机制，PR 描述不该只写“增加任务重试”，还可以附上三张候选卡：补偿操作的触发条件、补偿是否幂等、告警何时升级。审阅者能快速发现新逻辑究竟依赖现有的“安全重试”，还是需要独立的失败处理概念。这里的价值并非自动生成文档，而是迫使变更说明暴露被代码隐藏的假设。
卡片标签也要克制。标签适合做主题筛选，例如 api、security、reliability；不要用它复制层级关系。层级和顺序应由 prerequisites 表达，标签只用于横向查找。若同一张卡既依赖多个前提，又在多个主题中出现，可以先保持一张权威定义卡，再由不同卡组引用或解释它；避免为每个项目复制一份名称相同、内容渐渐分叉的“幂等键”。
一份适合 Agent 的检查清单
在让 Agent 根据卡组给出实现建议前，可以要求它按以下顺序返回结果：
- 列出使用到的卡片及其直接前置条件；
- 标明哪些结论来自卡片、哪些需要回查原始文档或代码；
- 对每一项代码建议指出会改变哪条约束；
- 当卡片间或卡片与实现间冲突时，停止生成“修复方案”，转而提出待确认问题；
- 变更完成后，提示维护者是否需要更新卡片内容或依赖边。
这个清单的重点是保留不确定性。MCP 让 Agent 能够读写知识卡，并不会让卡片自动具备版本控制、测试覆盖或授权判断能力。把“来源”和“待确认项”显式输出，才不会把一个便利的知识结构误用成自动化决策系统。
维护时的三个边界
卡片不是源代码真相。 卡片适合表达稳定的概念、约束和决策理由；函数签名、配置字段、版本和生产状态仍应回到仓库、API Schema 或运行时验证。把易变细节直接写进卡片，会很快制造过期知识。
导入前要保留人工审核。 JSON 格式正确不代表依赖正确。特别是由 LLM 初稿生成的卡组，应检查它是否把因果关系误写成前置关系，或把“通常如此”写成绝对规则。
注意资料的隐私边界。 Manthan 的隐私政策说明，上传的文档和生成的卡组会用于提供、存储和展示服务；其称不会把上传内容出售给第三方，也不会将其用于训练超出当次生成所需的 AI 模型。即便如此，涉及密钥、客户数据、未公开漏洞或受监管资料时，仍应先按组织的数据处理规则脱敏、审批或选择本地方案。
结语
对开发团队而言，Manthan 最有价值的地方不是再增加一个“AI 知识库”，而是提供一份能被人和 MCP 客户端共同读取的概念依赖结构。先把资料拆成小而可审阅的卡片，再谨慎标注真正的前置条件，最后让 Agent 把它当作约束与导航，而不是无条件事实来源。这样，文档进入 AI 工作流后仍保留了推理顺序、维护入口和人工复核点。