Potpie 全局 Agent 指令模板CLAUDE.md 精简管理块的设计与安装合并机制【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpiePotpie 向各编码 harnessClaude Code、Codex 等注入两类指令文件仓库内详细的项目级 bundle以及一份刻意做到极小的全局指令块。本文以模板文件 CLAUDE.md 为主体逐行解读这份全局指令的设计意图并结合 安装器源码 与 测试用例 说明它如何被安全地合并进用户已有的~/.claude/CLAUDE.md——读完你可以掌握这套托管 Markdown 管理块的完整机制标记定位、原地更新、幂等重跑与用户内容保护。模板原文一段 8 行的全局指令global_agent_bundle目录是 Potpie 模板体系中最小的一个 bundle仅包含两个内容相同的文件CLAUDE.md —— 面向 Claude Code 全局作用域AGENTS.md —— 面向 Codex 等以AGENTS.md为全局规则文件的 harness。CLAUDE.md的完整内容如下原文照录共 8 行有效文本!-- potpie-start -- Potpie is durable project memory: repo/source mappings, decisions, infra, changes, bugs, docs, and preferences for agents. Use it when it can materially help with repo context, prior decisions, architecture, bugs, or durable history. Do not run Potpie checks for simple QA or trivial edits. When useful, check mapping/graph health once per session (potpie --json source list, potpie --json graph status; skip if unavailable). Record only durable learnings. !-- potpie-end --注意首尾的!-- potpie-start --/!-- potpie-end --注释标记——它们不是装饰而是安装器定位托管区域的锚点下文会展开。逐句解读这份指令教给 Agent 什么尽管全文只有 6 句每句都对应一条明确的行为约束身份与内容边界第 2–4 行把 Potpie 定义为durable project memory枚举其承载内容——repo/source 映射、决策、基础设施、变更、缺陷、文档与偏好并给出使用条件当它能实质性地帮助获取仓库上下文、历史决策、架构、缺陷或持久历史时才使用。这防止 Agent 在每次任务中无差别地调用 Potpie。负面清单第 5 行Do not run Potpie checks for simple QA or trivial edits——简单的问答与琐碎编辑不触发 Potpie 检查控制全局指令在每个仓库、每次提示中重复加载带来的成本。频率约束第 6 行once per session——映射/图健康检查每会话只做一次而不是每步都查。具体命令与降级策略第 6–7 行给出两条可直接复制的命令potpie --json source list与potpie --json graph status且明确 skip if unavailable——Potpie 不可用时静默跳过不阻断 Agent 主流程。两条命令均使用--json说明期望输出是结构化数据供 Agent 解析。写入边界第 8 行Record only durable learnings——只记录持久性结论不做过程性噪音写入。安装器的 docstring 直接解释了为什么必须这么短见 installer.py 第 442–452 行def install_global_agent_instructions( root: str | Path, *, agent: str default, force: bool True, ) - InstallResult: Install compact global instructions for harnesses with file-based rules. The project bundle is intentionally detailed. This global bundle stays tiny because it can be loaded into every prompt across repositories. 即项目级 bundle 可以详细而全局 bundle 会被加载进跨仓库的每一条 prompt因此必须保持极小。这正是CLAUDE.md只有 8 行的设计原因。作为对照项目级的详细模板位于 agent_bundle/AGENTS.md 与 claude_bundle/CLAUDE.md其中包含完整的 skill 目录与读写闭环教学。安装路径从--agent参数到目标文件全局指令的入口函数是 install_global_agent_instructions。关键行为有三点agent 到文件名的映射agentclaude安装CLAUDE.mdagent为default或codex时安装AGENTS.md其余取值直接返回空结果不报错。这解释了为什么同一个 bundle 里有两个内容相同的文件。只挑单文件安装includelambda rel: rel.as_posix() filename保证只写入对应文件名merge_filesfrozenset({filename})则声明该文件走合并而非覆盖路径。安装根目录由调用方决定该函数本身不解析~/.claude而是由 harness 目标对象注入。目标接线在 potpie/skills/targets.py 中。FileBackedAgentTarget.install_support_files()第 70–78 行在技能安装后调用该函数刷新全局指令块具体各 harness 的路径配置为Harness全局指令文件路径来源claude~/.claude/CLAUDE.mdClaudeAgentTarget中instructions_rootPath.home() / .claudetargets.py 第 152–161 行codex~/.codex/AGENTS.mdCodexAgentTarget中instructions_rootPath.home() / .codextargets.py 第 174–183 行从源码结构看cursor与opencode两个目标未配置instructions_rootinstall_support_files()遇到None直接返回——即只有 Claude 与 Codex 拥有文件型全局指令与 CLI README 中for harnesses with documented file-backed global instructions的表述一致。触发方式上potpie skills install --agent claude以及首次运行的potpie setup --agent claude会同时安装推荐技能并刷新这个管理块skills.md 进一步说明该刷新发生在安装/更新技能的流程里即使技能本身已是最新测试test_skill_manager_repairs_support_files_when_skill_is_current验证了这一点技能版本一致时不重装技能但install_support_files仍会被调用一次用于修复缺失或漂移的管理块。合并机制标记定位与三种结果这是整个模板机制的技术核心。installer.py 第 15–19 行 定义了两个正则_MANAGED_MARKER_RE re.compile( r!-- (?:context-engine|potpie)-start --.*?!-- (?:context-engine|potpie)-end --, re.DOTALL, ) _DEFAULT_MERGE_FILES frozenset({AGENTS.md, CLAUDE.md})标记正则同时兼容context-engine与potpie两种历史前缀意味着早期以!-- context-engine-start --安装的旧文件也能被识别并原地替换。真正的合并逻辑在 _merge_managed_markdown按优先级依次尝试四种情形已有托管标记正则命中用新模板整体替换标记之间的内容替换前后文本相同则记为unchanged否则updated。用户写在标记之外的内容完全不动。文件内容恰好等于去标记后的模板正文视为未加标记的托管内容补上标记。文件包含去标记后的模板正文_strip_managed_markers剥掉首尾标记行后做子串匹配把正文替换为带标记的新版本。这一分支覆盖用户手工复制过旧内容、但没有完整标记对的场景。都不命中在文件末尾追加\n\n 新模板段文件原为空记为created否则updated。安装动作的结果通过InstallResult的created / updated / unchanged / skipped四个列表向上汇报供 CLI 输出与测试断言使用。合并只针对AGENTS.md/CLAUDE.md两个文件名生效_DEFAULT_MERGE_FILESbundle 中其他文件走普通的存在且不一致则跳过、force时才覆盖逻辑见 _install_file。测试如何验证不破坏用户内容tests/unit/test_agent_installer.py 中的两个用例覆盖了模板最核心的契约test_install_global_agent_instructions_merges_compact_agents_md第 102–124 行预置一个只含# Personal defaults的用户AGENTS.md安装后断言用户内容仍在、模板正文与potpie --json source list命令已进入标记区断言标记区内非空行不超过 6 行——这是对全局块保持极小这条设计约束的可执行校验立即重跑一次安装断言结果为unchanged——验证幂等性重复执行不产生无意义写入。test_install_global_agent_instructions_updates_managed_claude_section第 127–144 行预置CLAUDE.md中带有!-- potpie-start -- old !-- potpie-end --的旧托管段安装后断言用户标题保留、旧内容old被清除、新模板正文就位——验证标记间原地更新分支。此外 test_file_backed_target_installs_global_support_files 验证了FileBackedAgentTarget.install_support_files()端到端写出~/.codex/AGENTS.md形态的托管块。使用方式与适用前提以发布包用户视角完整流程为# 安装 potpie发布包方式 uv tool install potpie # 或 pip install potpie # 为 Claude Code 安装推荐技能同时刷新 ~/.claude/CLAUDE.md 的托管块 potpie skills install --agent claude # 查看/更新/移除来自 CLI README 与 skills.md 的命令面 potpie skills status --agent claude potpie skills update --agent claude potpie skills remove --all --agent claude适用前提与限制需要明确该模板是仓库内的源文件运行时由 potpie/cli/README.md 描述的potpie skills install/potpie setup --agent流程物化到用户机器的~/.claude/CLAUDE.md仓库本身不要求你手动编辑它安装器读取模板使用的是importlib.resources打包路径_iter_bundle_files且会跳过__pycache__与.pyc/.pyo因此以仓库源码方式安装时也不会把测试运行残留带进用户目录对cursor/opencode等未配置指令根的目标不产生任何全局指令文件模板中的potpie --json source list、potpie --json graph status在 Potpie 服务不可用时按指令本身要求跳过不影响 Agent 正常工作。小结global_agent_bundle/CLAUDE.md是 Potpie双粒度指令体系中的全局端内容上是一份 6 句的行为约束何时用、何时不用、每会话一次健康检查、只记录持久结论工程上依赖!-- potpie-start --/!-- potpie-end --标记实现替换托管区、保留用户区的合并语义并以标记区非空行不超过 6 行的测试守住体积下限。理解这个模板也就理解了 Potpie 如何在不与用户已有指令冲突的前提下把 Potpie 的使用纪律注入到跨仓库的每一次会话中。更多背景可参阅 Skills 文档 与 CLI README。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考