sergeylopukhov/context-cartographer

Context Cartographer

构建一个小型文档系统，让未来的助手只加载它们所需的上下文。

范围边界

• 在文档系统设置、审计、迁移、清理、重组或所有权不明确时使用此技能。
• 在目标所有者文件已知且仅进行常规编辑时，不要使用此技能。
• 在 AGENTS.md、CLAUDE.md、Cursor 规则、docs/architecture.md 或 docs/code_rules.md 已要求的自动持续维护中，不要使用此技能。请直接应用那些本地指令。
• 当用户显式调用 context-cartographer 时，始终使用此技能。

核心规则

• 在读取项目文件之前，先解析项目根目录并清点实际路径。不要根据当前目录或其他项目猜测路径。
• 重用任务期间已读取的文件。仅重新读取已更改的文件、截断的输出或特定的未读范围。
• 保持根级助手指令文件简短。将持久的主题细节放在 docs/ 下的所有者文件中。
• 使用 AGENTS.md 用于 Codex，CLAUDE.md 用于 Claude Code，.cursor/rules/context-cartographer.mdc 用于 Cursor，或为选定的多助手目标使用精简适配器。
• 在提出更改之前，先以只读方式检查。
• 保留项目特定的现有规则，并进行精准编辑。
• 未经批准，绝不要覆盖、移动、合并或删除现有的指令或文档文件。
• 仅创建有项目证据支持且当前需要的文件。
• 将未知事实标记为 TODO: clarify；绝不要编造项目事实。
• 默认将项目记忆文档设为仅本地，并将其添加到仓库忽略文件中，除非用户明确要求跟踪或发布它们。
• 编辑后验证链接、所有者路由、忽略规则和陈旧引用。

必需决策

在创建或替换根级助手指令之前，需要解决以下问题：

• 助手目标；
• 代码规则模式：使用 docs/code_rules.md 或不使用；
• 文档维护模式：自动持续维护 或 仅按请求维护；
• 处理现有文档：保持原样、仅审计、批准后迁移，或让助手决定；
• 项目记忆文档保持仅本地还是被跟踪。

不要推断代码规则模式或文档维护模式。当缺少两个以上的决策时，使用捆绑的问卷。

生成的根指令必须使常规维护独立于此技能：

• 在 自动持续维护 模式下，每当完成的工作更改了持久行为、架构、设置、部署、阶段、测试数据、访问、导入/导出、公共 URL、操作工作流、数据模型、公共接口、助手工作流或文档所有权时，在同一任务中更新匹配的所有者文档。
• 在 仅按请求维护 模式下，仅在明确要求时更新文档，并标记可能陈旧的文档。
• 声明常规维护直接使用根指令和现有的所有者文档，而无需调用 context-cartographer。
• 如果没有现有的所有者文件匹配，则调用此技能并遵循缺少所有者协议。在自动持续维护模式下，自动分类并创建最小的合理所有者，而无需仅为了创建 Markdown 文件而征求许可。
• 之后仅用于设置、审计、迁移、清理、重组、显式使用或真正所有权不明确的情况。

参考路由

• 对于首次设置，始终读取 references/setup-workflow.md；它会路由其他必需的参考文件。
• 对于审计、迁移、清理、重组或所有权不明确的情况，始终读取 references/existing-docs-workflow.md；它会路由其他必需的参考文件。
• 在选择文件或所有权之前，读取 references/doc-map.md。
• 在创建根指令或 docs/*.md 之前，读取 references/file-templates.md。
• 在审计现有仓库之前，读取 references/audit-checklist.md。
• 在拆分、合并、删除或重命名文档之前，读取 references/cleanup-rules.md。
• 在创建问卷 JSON 之前，读取 references/question_schema.md。
• 仅在调整问卷流程时，读取 references/questionnaire_usage_examples.md。

工作流程

1. 使用 rg --files 解析项目根目录和路径清单。
2. 分类项目概况、选定的助手目标、现有文档、所有权、代码规则模式和维护模式。
3. 对于现有文档，在编辑之前，显示当前文件、主题所有者和计划的创建/更新/删除操作的紧凑映射。
4. 在用户授权的范围内应用最小的合理文档系统更改。
5. 验证链接、过时的文件名、所有者覆盖范围、仅本地忽略规则和独立的常规维护指令。

对于新系统，遵循 references/setup-workflow.md。

对于审计、清理、迁移、重组或所有权不明确的情况，遵循 references/existing-docs-workflow.md。

问卷

对于缺少两个以上决策的广泛设置工作：

1. 从 references/question_schema.md 创建 .project-questionnaire/questions.json。
2. 将 language 设置为用户或项目语言。
3. 使用 python3 <this-skill>/scripts/questionnaire_server.py --input .project-questionnaire/questions.json --validate-only 进行验证。
4. 在 127.0.0.1 上使用自动端口运行服务器。
5. 在用户保存并声明完成后，在继续之前读取两个答案文件。

代码规则模式和文档维护模式必须是必需的选择，没有默认值或推荐选项。

更新检查

每天最多运行一次 python3 <this-skill>/scripts/check_update.py --json。在安装可用更新之前征求许可。在发布更改时，将 VERSION 更新，以便已安装的用户能够收到。

退出条件

报告：

• 创建或更改的文件；
• 链接、路由和陈旧引用已检查；
• 仅本地忽略策略已检查；
• 独立的自动维护路由已检查；
• 已执行的验证以及未运行的任何检查。