用途:让 ctx 在已有、通常较杂乱的项目上生效,尽量不改动用户现有结构,只新增 /ctx 挂载点和一行指针。核心原则是稳定挂载点、可替换后端:agent 始终读取 <repo>/ctx,它是真实目录还是符号链接属于部署细节。
主要能力与流程: EP1 选择后端。若项目已发布(LICENSE + 公开远端 + 包注册表痕迹),用外部符号链接 <repo>/ctx -> ../<project>-ctx/,符号链接加入 gitignore,真实内容放在代码仓库之外;否则默认仓库内真实目录 <repo>/ctx。外部存储默认放在同级目录,不擅自创建中央存储。 EP2 声明指针。若存在 AGENTS.md 则加指针行;若只有 CLAUDE.md 则加到 CLAUDE.md;都没有则由当前 agent 写自己的原生文件(Claude Code 用 CLAUDE.md,Codex/Cursor/Windsurf 等用 AGENTS.md)。若用 AGENTS.md 且运行的是 Claude Code,还需确保 CLAUDE.md 以 @AGENTS.md 导入。指针行内容为:Project context & docs live in ./ctx — managed by the ctx skills; apply their consistency rules when editing ctx docs. EP3 整理散落文档。扫描文档类内容,按生命周期分类并委派给领域技能:笔记/研究交给 ctx-merge;现行设计/架构进 spec/ 交给 ctx-spec;已定决策进 decisions/ 交给 ctx-spec;状态/待办进 progress/ 交给 ctx-progress;供人审阅的文档进 reports/ 交给 ctx-report;原始笔记/实验进 scratch/ 保持原样。先生成迁移计划给用户确认,未批准前不移动任何内容,且不碰代码文件。 EP4 代码拓扑检查。最后评估仓库是否值得结构性调整,仅作为建议提出,默认尊重现状,只在用户要求或构建 ctx 导致不可避免时才行动。
完成标准:/ctx 挂载点位置与后端正确;指针行写入正确文件;若后端含机密且代码仓库公开,/ctx 必须是 gitignore 的对外符号链接且确认从未提交;迁移计划已产出(批准后执行);通过 ctx 文件夹的 DoD 检查清单。
限制:不重构用户现有目录,只新增挂载与指针;默认用最轻后端,仅在确实需要分离时升级;不重新实现领域技能的写作格式;不移动代码文件。相关技能:ctx、ctx-merge、ctx-spec、ctx-progress、ctx-report。