Spec Kit agent-context 扩展深度解析如何让 CLAUDE.md、AGENTS.md 与 Plan 自动保持同步【免费下载链接】spec-kit Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kitSpec Kit 的agent-context扩展负责管理编码智能体Claude Code、Copilot、Cursor、Gemini 等的上下文/指令文件例如CLAUDE.md、AGENTS.md、.github/copilot-instructions.md。它是一个显式安装opt-in的可选扩展安装后它会在这些文件中维护一段由可配置标记包围的受管区块并自动把区块内容指向当前最新的plan.md路径不安装则 Spec Kit 的任何流程都不会改动这些文件。读完本文你将掌握该扩展的安装/禁用方式、全部配置项含义、受管区块的 upsert 算法、plan 路径的解析优先级以及.mdc文件的 frontmatter 修复机制。为什么做成一个扩展而不是内置功能不是每个 Spec Kit 用户都希望 Spec Kit 去写编码智能体的上下文文件。把这一行为放进一个独立的 opt-in 扩展见 extensions/agent-context/README.md带来四个直接好处可选择是否安装——specify init默认不会安装它。想要 Spec Kit 托管 agent 上下文文件时才显式添加未安装时该文件绝不会被修改已禁用时其自动钩子也不会运行。可自定义标记——编辑项目内的.specify/extensions/agent-context/agent-context-config.yml脚本会遵循其中context_markers的取值。可同步多个 agent 锚点——当项目同时使用多份上下文文件如AGENTS.md和CLAUDE.md时配置context_files列表即可一次更新全部文件。可按需刷新——在 agent 中运行speckit.agent-context.update命令或依赖 extension.yml 中声明的after_specify、after_plan钩子自动刷新。从源码结构看这一完全交给扩展自己的设计在 CLI 侧有对应约束specify_cli的集成初始化代码如 src/specify_cli/integrations/_helpers.py明确注释agent 上下文文件完全由 opt-in 的 agent-context 扩展拥有该函数从不触碰扩展及其配置并且测试 tests/extensions/test_extension_agent_context.py 中的test_cli_does_not_resolve_context_placeholder专门验证了 CLI 不再解析模板中的__CONTEXT_FILE__占位符——当扩展未安装或被禁用时模板里的__CONTEXT_FILE__会原样保留。受管区块的生命周期只动标记之间的内容该扩展的核心职责是拥有由 start/end 标记默认!-- SPECKIT START --/!-- SPECKIT END --分隔的受管 section 的完整生命周期只写标记之间区块外的任何内容都不受影响对.mdc文件额外保证文件顶部 YAML frontmatter 中包含alwaysApply: trueCursor 只自动加载带此字段的.mdc规则文件幂等重复运行只会替换旧区块不会叠加。受管区块的固定内容由 _build_section 生成!-- SPECKIT START -- For additional context about technologies to be used, project structure, shell commands, and other important information, read the current plan at specs/001-login/plan.md !-- SPECKIT END --即一句提示语加上当前 plan 的路径。这样当编码 agent 读取CLAUDE.md时就能被引导去读最新的实现计划。安装、禁用与命令安装在已初始化的 Spec Kit 项目根目录运行specify extension add agent-context禁用 / 重新启用specify extension disable agent-context # 重新启用 specify extension enable agent-context禁用或未安装期间Spec Kit 中没有任何流程会创建、更新或删除受管区块模板中的__CONTEXT_FILE__占位符保持原样扩展自身的配置也永远不会被读取。提供的命令命令说明speckit.agent-context.update用当前 plan 路径刷新 agent 上下文文件中的受管区块命令 ID 是规范的canonical写法实际调用语法取决于你的集成方式集成类型调用写法dot-command 集成/speckit.agent-context.updatehyphen/skills 集成含 Forge、Cline 等/speckit-agent-context-updateCodex、ZCodeskills 模式$speckit-agent-context-updateKimi/skill:speckit-agent-context-update对应的命令模板见 extensions/agent-context/commands/speckit.agent-context.update.md其声明的执行入口为Bash.specify/extensions/agent-context/scripts/bash/update-agent-context.sh [plan_path]PowerShell.specify/extensions/agent-context/scripts/powershell/update-agent-context.ps1 [plan_path]当省略plan_path参数时脚本会自动探测最新的specs/**/plan.md。配置参考agent-context-config.yml所有配置都集中在项目内的.specify/extensions/agent-context/agent-context-config.yml。仓库中的模板extensions/agent-context/agent-context-config.yml完整注释了每个字段的用途可逐项对照理解# 单个 agent 上下文文件路径相对项目根即 .specify/ 所在目录。 # 拒绝绝对路径、反斜杠分隔符和 .. 路径段。 # 留空时使用你所选编码 agent 的默认上下文文件 # 见 agent-context-defaults.json。 # 例: context_file: CLAUDE.md context_file: # 多个 agent 上下文文件列表相对项目根。 # 当 context_file 与 context_files 同时存在时context_files 优先生效。 # 例: # context_files: # - AGENTS.md # - CLAUDE.md context_files: [] # 受管区块的起止标记。扩展只在这两个标记之间注入信息。 # 仅在希望自定义标记名时修改。 # 例: # context_markers: # start: !-- AGENT SPEC KIT CONTEXT START -- # end: !-- AGENT SPEC KIT CONTEXT END -- context_markers: start: !-- SPECKIT START -- end: !-- SPECKIT END --要点归纳配置项类型行为context_file字符串可选指定单个受管文件留空则回退到集成默认映射context_files字符串列表可选多个受管文件非空时优先于context_file逐一遍历更新context_markers.start/.end字符串可选受管区块分隔符缺失时使用默认!-- SPECKIT START --/!-- SPECKIT END --路径安全约束_validate_context_fileextensions/agent-context/scripts/python/update_agent_context.py#L112-L138对每个候选路径做硬性校验违反即报错退出退出码 1必须以项目根为相对路径——绝对路径/...与 Windows 盘符路径C:\...被拒绝不得包含反斜杠分隔符不得包含..路径段最终解析含符号链接解引用后仍必须落在项目根之内防止通过 symlink 逃逸出项目目录。bash 脚本中的test_bash_script_rejects_symlink_escape对应测试tests/extensions/test_extension_agent_context.py专门覆盖了这一逃逸场景。未配置时的自播种self-seed当context_file与context_files都为空时脚本并不会报错而是执行自播种逻辑读取.specify/init-options.json中的integration或ai键再通过 extensions/agent-context/agent-context-defaults.json 中的映射得到默认上下文文件。该映射覆盖了全部 36 个支持的集成摘选如下集成 key默认上下文文件claudeCLAUDE.mdcopilot.github/copilot-instructions.mdgeminiGEMINI.mdcursor-agent.cursor/rules/specify-rules.mdccodex/copilot之外的多数 CLIcodex、goose、grok、opencode、qwen等AGENTS.mdjunie.junie/AGENTS.mdkilocode.kilocode/rules/specify-rules.mdtrae.trae/rules/project_rules.mdqwen/qodercli/shai/tabnine/zcodeQWEN.md/QODER.md/SHAI.md/TABNINE.md/ZCODE.md源码注释明确指出这一映射按设计独立于 Specify CLI——扩展自己管理自己的生命周期脚本内部不 import 任何specify_cli模块。若集成在映射表中不存在默认值脚本会打印no default context file is known for integration …的提示要求用户显式设置context_file。此外在 Windows/Cygwin/MSYS 环境下context_files的去重比较采用大小写不敏感casefold策略与 bash 脚本中MINGW/MSYS/CYGWIN分支的行为一致。底层实现Plan 路径如何被解析这是扩展最有技术含量的部分。受管区块的价值完全取决于plan_path是否指向当前计划因此解析采用两级优先策略见 _resolve_plan_path优先读取.specify/feature.json——该文件由/speckit-specify写入其中feature_directory字段指明当前功能目录脚本在feature_directory/plan.md存在时以它为准。解析时做了几处细节处理先把路径中的反斜杠PowerShell 在 Windows 上写入的格式规范化为正斜杠支持相对路径、绝对路径与C:/盘符路径三种形态先resolve()解引用符号链接再做relative_to比较使 macOS 上/var/…与/private/var/…被判定为同一路径若 plan 落在项目根外则直接输出解析后的 POSIX 绝对路径。回退到 mtime 探测——仅当feature.json不存在或其 plan 尚未生成时递归遍历specs/下所有plan.mdrglob而非旧的单层specs/*/plan.md通配选出修改时间最新的一个。递归搜索保证了通过SPECIFY_FEATURE_DIRECTORY创建的作用域化布局如specs/scope/feature/plan.md也能被发现。同样候选文件在比较前先做符号链接解引用避免指向项目外的specs/symlink 被误选。这条解析链有专门的回归测试tests/extensions/test_update_agent_context_feature_json.py 覆盖 feature.json 路径test_bash_script_discovers_nested_plan/test_bash_script_finds_nested_plan等用例覆盖嵌套布局的 mtime 回退。底层实现区块 upsert 的四分支算法_upsert_sectionbash/PowerShell 版本逻辑等价按文件中现有标记的组合分四种情况处理现有文件状态行为start 与 end 标记均存在整体替换标记之间的旧区块保留标记后的换行只有 start 标记从 start 标记处开始截断写入新区块丢弃残缺尾部只有 end 标记保留 end 标记之后的内容在其前面插入新区块都没有标记若文件已有内容则追加到文件末尾先补齐换行文件不存在则直接创建父目录不存在时自动mkdir -p写入前还会把全文 CRLF/CR 统一规范化为 LF读取时以utf-8-sig编码容忍 BOM保证跨平台换行稳定。bash 入口脚本还负责解释器选择依次尝试$SPECKIT_PYTHON环境变量、python3、python并要求该解释器可import yaml且为 Python 3见 update-agent-context.sh 第 29-55 行任何一个不可用则降级为打印警告并跳过更新而不是让钩子失败。.mdc 文件的 frontmatter 修复ensure_mdc_frontmatterupdate_agent_context.py 第 216-256 行只对.mdc后缀文件生效处理三种情形文件无 frontmatter → 在头部整体前置---\nalwaysApply: true\n---\n\nfrontmatter 已有alwaysApply: true→ 原样返回幂等frontmatter 存在但alwaysApply缺失或值不是true→ 原地修复该行、保留原有注释与格式若完全没有该键则在 frontmatter 末尾追加一行。对应测试test_bash_script_prepends_mdc_frontmatter、test_bash_script_mdc_frontmatter_is_idempotent、test_bash_script_repairs_existing_mdc_frontmatter以及非 .mdc 文件不做 frontmatter 处理的负向用例都在 tests/extensions/test_extension_agent_context.py 中可查证。钩子驱动的自动化extension.yml 声明了两个可选钩子hooks: after_specify: command: speckit.agent-context.update optional: true description: Refresh agent context after specification after_plan: command: speckit.agent-context.update optional: true description: Refresh agent context after planning也就是说每次执行/speckit.specify与/speckit.plan之后事件系统会自动触发speckit.agent-context.update使上下文文件中的 plan 路径始终跟上最新进度——无需手动干预。根据 extensions/EXTENSION-API-REFERENCE.md钩子挂在after_specify、after_plan等由核心命令定义的生命周期事件上同一事件的多个钩子按priority升序执行默认 10。extension.yml同时声明了元信息schema_version: 1.0、要求speckit_version: 0.2.0、标签agent/context/core且该扩展以捆绑bundled形式随仓库分发catalog中将其列为 bundled 条目测试test_catalog_lists_agent_context_as_bundled守护此约定。环境要求与故障排查捆绑的更新脚本要求Python 3 PyYAML做 YAML 解析/写入PowerShell 侧在可用时也可用ConvertFrom-Yaml。PyYAML 随specifyCLI 一起分发正常情况下同一个python3解释器即可满足。如果钩子报告 PyYAML is required … not available in the current Python environment说明系统python3与安装 Spec Kit 所用的解释器不是同一个解决方式pip install pyyaml # 或者针对 Spec Kit 实际使用的那个解释器 /path/to/speckit-python -m pip install pyyaml脚本在 PyYAML 缺失时的行为是优雅降级打印指引信息后以退出码 0 跳过本次更新上下文文件不被修改避免破坏宿主命令流程测试test_bash_script_falls_back_from_invalid_speckit_python验证了无效SPECKIT_PYTHON会被自动回退到 PATH 上其他可用解释器。验证与测试入口该扩展的行为有相当完整的测试护栏均位于 tests/extensions/ 目录可作为实现是否符合文档的一手证据tests/extensions/test_extension_agent_context.py——扩展清单/文件完整性、bash 与 PowerShell 脚本的路径拒绝、去重、嵌套 plan 发现、.mdcfrontmatter 幂等与修复、符号链接/junction 逃逸拒绝以及CLI 不解析__CONTEXT_FILE__占位符的职责边界tests/extensions/test_update_agent_context_feature_json.py——feature.json 驱动的 plan 解析tests/extensions/test_update_agent_context_python_parity.py 与 tests/extensions/test_agent_context_cli_free.py——Python 版脚本与 shell 版的行为一致性以及扩展脚本不依赖 specify CLI的独立性。bash、PowerShell、Python 三个运行时的脚本scripts/bash/update-agent-context.sh、scripts/powershell/update-agent-context.ps1、scripts/python/update_agent_context.py在语义上互为孪生实现配置解析、自播种、路径校验、plan 解析与 upsert 逻辑逐条对齐跨平台行为以测试为准绳。小结agent-context是 Spec Kit 扩展体系中一个边界清晰、职责单一的范本它以 opt-in 的方式接管编码 agent 上下文文件把让 agent 知道最新 plan 在哪这件容易被遗忘的小事变成after_specify/after_plan钩子驱动的自动行为。对使用者的实际收益是——在 Claude Code、Copilot、Cursor 等工具中始终有一份指向当前specs/**/plan.md的新鲜指引而标记之外的文件内容团队手写的规则、项目约定永远不会被覆盖若你更倾向自行维护该文件不安装扩展即可Spec Kit 的其余部分对此完全无感。【免费下载链接】spec-kit Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考