codecontext-setup

Codecontext 配置

配置 codecontext，让 Agent 无需猜测即可使用它。

这项技能的目的不只是安装软件包。真正的工作是让仓库的 Agent 约定保持一致：

• 在适当的位置安装工具链
• 在 AGENTS.md 中说明 Agent 何时以及如何使用它
• 将行内 @context 视为必需的结构化层
• 不限制辅助引用，并由用户掌控

不要臆造必需的旁置文档模式。不要要求使用 .ctx.md。 引用可以指向 Markdown、HTML、文本、图表、导出的文档，或仓库使用的任何其他可解析文件。

使用时机

用户要求进行以下操作时，使用此技能：

• 安装或采用 codecontext
• 更新仓库的 AGENTS.md 或围绕 @context 的 Agent 指南
• 审查项目当前的 codecontext 配置
• 调和 codecontext 工具与仓库说明之间的不一致
• 改进 Agent 发现决策、风险、假设和历史信息的方式

预期结果

完成此工作流后，仓库应具备：

• 清晰的 AGENTS.md codecontext 章节
• 合理的 Agent CLI 工作流
• 适用于仓库语言和工具链的正确强制执行方式
• 不存在有关结构化旁置文档的误导性指南

工作流

1. 审查当前状态

检查：

• 软件包管理器和工作区布局
• 仓库是否已依赖 @recallnet/codecontext-cli
• 仓库是否已依赖 @recallnet/codecontext-eslint-plugin
• 仓库是否已有 Python、Go、Rust 或其他语言原生的
• 仓库是否已有 Python、Go、Ruby、Rust 或其他语言原生的 检查器，适用于 codecontext 应当强制执行的地方
• 是否存在 ESLint，以及共享配置所在位置
• 仓库根目录和子目录／工作树中是否存在 AGENTS.md
• 现有 Agent 文档是否提及 @context、codecontext、ADR、 contexts/ 或决策日志

留意两种常见问题：

1. 已安装工具，但没有 Agent 工作流或指南
2. 已有指南，但内容过时、相互矛盾，或指向并不存在的策略

2. 确定安装范围

仅安装最低限度的实用组件：

• 当 Agent 需要运行 --scope、--diff 或 --report 时，安装 @recallnet/codecontext-cli
• 当仓库使用 ESLint 并需要验证注释时，安装 @recallnet/codecontext-eslint-plugin
• 当仓库的主要强制执行方式依赖 Python、Go、Rust 或 ESLint 之外的 其他工具时，使用语言原生的检查器或分析器
• 仅当仓库中有自定义代码直接导入解析器 API 时，才安装 @recallnet/codecontext-parser

不要添加仓库不会使用的软件包。

3. 在修改软件包之前或同时修正 AGENTS.md

没有 Agent 说明，codecontext 配置就不完整。

每个仓库级 AGENTS.md 章节都应涵盖：

• @context 的用途
• 何时需要添加注释
• 一套精简的首选分类
• 编辑前和编辑后的工作流
• 引用可以是什么，以及不可以是什么
• 反模式

如果子目录中的 AGENTS.md 指向仓库级策略，请确保该策略确实存在。

推荐的 AGENTS.md 约定

保持简短。一个合适的章节通常包含 8-14 条要点。

可采用类似以下内容：

- **codecontext**: Use inline `@context` annotations for non-obvious,
  high-value reasoning that future edits could easily erase.
  - Required for:
    - critical decision logic and invariants
    - security-sensitive behavior and hard-won lessons
    - external integration quirks and contract mismatches
    - regression guards explaining why a simpler change would be wrong
  - Preferred forms: `@context decision`, `@context risk`,
    `@context requirement`, `@context history`
  - Keep notes short and specific: what is true, why it matters, and what
    would break if changed
  - Use `{@link ...}` for supporting material when helpful, but refs are just pointers
    to repo files or docs. Do not require any special doc schema.
  - Before editing critical files, run:
    `npx @recallnet/codecontext-cli --scope <file>`
  - After editing, run:
    `npx @recallnet/codecontext-cli --diff HEAD <file>`
  - For broader orientation in larger repos, run:
    `npx @recallnet/codecontext-cli --report`
  - Do not use `@context` for obvious narration, duplicated ADR prose, or
    generic comments.

只有当仓库明确需要超出基线（decision、risk、requirement、history）的分类时，才调整分类。谨慎添加额外类别。

对使用 ADR 或拥有大型文档树的仓库的建议

如果仓库已使用 ADR、计划、运行手册或架构文档：

• 将 @context 保留为面向 Agent 的行内层
• 将引用视为可选的扩展目标
• 不要默认要求 Agent 浏览整个文档树
• 不要将完整 ADR 内容逐字复制到行内

正确的模式是：

• @context 承载结构化的本地信号
• 引用指向任意辅助材料
• Agent 仅在需要时展开引用

Refs 策略

明确说明：

• refs 可以指向 .md、.html、.txt、图表、导出文件或其他仓库文件
• 并非每条注释都必须带 refs
• refs 不应对目标文件施加架构要求

不要编写暗示以下内容的指导：

• 必须使用 .ctx.md
• 必须使用 frontmatter
• 链接的文件必须可由机器解析

CLI 工作流指导

如果已安装 CLI，请在 Agent 文档中推荐以下命令：

npx @recallnet/codecontext-cli --scope path/to/file.ts
npx @recallnet/codecontext-cli --diff HEAD path/to/file.ts
npx @recallnet/codecontext-cli --report

使用 --report 了解仓库情况并审查决策。针对具体编辑，使用 --scope 和 --diff。

强制执行指导

如果仓库已有共享 ESLint 配置，请将插件集成到其中。 优先在中央位置强制检查语法以及过时或无效的 refs，而不是要求 Agent 自行检查。

如果仓库不使用 ESLint，不要仅仅为了 codecontext 强行引入它。 优先使用适合仓库实际技术栈的原生强制执行方式：

• Python 仓库：原生检查器或通过 PyPI 分发的工具
• Go 仓库：分析器 / golangci-lint 集成
• Ruby 仓库：原生检查器 gem 或 RuboCop 风格的集成
• Rust 仓库：crate / Clippy 风格的集成
• 混合技术栈或与工具无关的仓库：初期使用 CLI 工作流可能就足够

重要的问题不是“我们是否安装了 ESLint 插件？” 而是“在这个生态系统中，究竟是什么在强制检查 @context 的正确性？”

审查时的关注点

将以下情况标记为设置缺陷：

• 子级 AGENTS.md 文件指向不存在的仓库策略
• 提到 @context，但没有提供工作流的说明
• 在大型仓库中忽略 --report 的工作流指导
• 将链接文档视为必需的结构化附属文件的指导
• 安装了软件包，却没有相应的 Agent 文档
• 默认要求 Agent 阅读庞大的 ADR / 文档目录的文档

交付

完成设置或审计工作后：

1. 说明安装或更改了什么
2. 指出修复的任何过时或矛盾的 AGENTS.md 指导
3. 说明任何尚存的缺口
4. 如果没有安装强制执行机制，请解释原因

默认建议

如果仓库没有现有的 codecontext 指导，建议优先在根目录的 AGENTS.md 中创建 codecontext-setup 部分，而不是一开始就将说明分散到多个子级文档中。