用途
ai-context-refresh 用于管理项目根级 AI 上下文文件(CLAUDE.md、AGENTS.md)的生命周期,包括生成、智能合并、重构以及刷新 Codex 投影镜像。它面向需要让 AI 代理在项目中稳定获得项目级上下文、同时避免人工维护重复内容的工作流。
主要能力
- 生成与更新根上下文:读取 docs/project-config.json 和模板,按分段标记生成 CLAUDE.md;更新模式仅替换标记之间的内容,保留标记外的项目自有文本。
- 智能合并:当 CLAUDE.md 存在但没有分段标记时,按 ## 标题匹配已知分段键,将匹配段落包裹标记并替换内容,未匹配的用户段落原样保留。
- 纯 AI 重构:AI 读取整份 CLAUDE.md,去除冗余、合并表格、缩短冗长解释,在保留所有分段标记的前提下提升 token 效率。
- Codex 镜像同步:在最终 AI 编辑与验证完成后,直接运行共享同步运行器并传 --skip=claude-md,从完成后的 CLAUDE.md 重新生成 AGENTS.md、.agents/、.codex/ 等镜像,并验证各镜像。
- 条件分段:仅当配置中存在对应数据时才生成某分段,无数据则省略而非留空占位。
- 旧内容清理:更新模式可报告 LEGACY_UNIVERSAL_CONTENT,并支持通过 --strip-legacy-universal 在备份后移除旧版写入的通用分段与受管块。
- 路径规则内联与按需注入:当 contextGroups[].rules 使根文件超出字节预算时,可设置 portability.inlinePathRules 为 false,由文件约定钩子在匹配文件被触及时注入完整规则,并提供 --lookup CLI 作为非自动读取途径。
使用方式
该技能依赖 Node.js 与 docs/project-config.json。先通过 --detect 检测模式(缺失 CLAUDE.md 为 init、带标记为 update、无标记为智能合并、显式 --mode 可覆盖)。随后运行生成脚本,例如:
node .claude/skills/ai-context-refresh/scripts/generate-claude-md.cjs --mode init
node .claude/skills/ai-context-refresh/scripts/generate-claude-md.cjs --mode update
node .claude/skills/ai-context-refresh/scripts/generate-claude-md.cjs --mode update --strip-legacy-universal
脚本先生成机械部分,随后由 AI 填写项目描述、黄金规则、决策速查、命名约定等创造性内容,并进行验证。最终 CLAUDE.md 编辑完成后,直接运行:
node .claude/skills/sync-codex/scripts/run-codex-sync.mjs --skip=claude-md
若运行器失败,应报告失败阶段并保持任务未完成,不得声称 Codex 镜像已更新。
适用场景
- 新项目首次建立根级 AI 上下文。
- 已有带标记的 CLAUDE.md 需要增量同步配置变更。
- 已有无标记文档需要智能合并生成分段。
- 需要优化 CLAUDE.md 的 token 效率与结构。
- 根上下文更新后需要刷新 Codex 镜像。
限制
- 依赖 docs/project-config.json 作为主要数据源。
- 依赖 Node.js 运行生成脚本。
- 不运行钩子的宿主环境不受支持;工作流路由仅由钩子投递,不写入受跟踪文件。
- 无标记根文件视为项目自有,预检不会覆盖,需显式运行更新模式进行智能合并。
- 自定义路由协议仅运行时生效,不得写入受跟踪的 CLAUDE.md/AGENTS.md。
- 生成的分段内容不应手工编辑,应在构建器、模板或配置中修复后重新生成。
- 本技能与 sync-codex 为两个独立面向用户的技能,但共享同一执行流水线;交接直接调用运行器,不嵌套调用技能以避免递归。