codecontext-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codecontext Setup

Codecontext设置

Set up

codecontext

so agents can use it without guessing.

The point of this skill is not just package installation. The real job is to make the repo's agent contract coherent:

the toolchain is installed where it belongs
```
AGENTS.md
```
tells agents when and how to use it
inline
```
@context
```
is treated as the required structured layer
supporting refs stay unconstrained and user-owned

Do not invent required sidecar document schemas. Do not require

.ctx.md

. Refs can point to Markdown, HTML, text, diagrams, exported docs, or any other resolvable file the repo uses.

设置

codecontext

，让Agent无需猜测即可直接使用。

本技能的核心目标不只是完成软件包安装，真正的工作是让代码仓库的Agent契约清晰一致：

工具链安装到了正确的位置
```
AGENTS.md
```
明确告知Agent何时以及如何使用codecontext
行内
```
@context
```
被视为必填的结构化信息层
支持引用保持无约束，完全由用户自主掌控

不要自行发明必填的附属文档schema，不要强制要求使用

.ctx.md

。引用可以指向Markdown、HTML、文本、流程图、导出文档，或是代码仓库使用的其他任何可解析文件。

When to use

何时使用

Use this skill when the user asks to:

install or adopt
```
codecontext
```
update a repo's
```
AGENTS.md
```
or agent guidance around
```
@context
```
audit a project's current
```
codecontext
```
setup
reconcile a mismatch between codecontext tooling and repo instructions
improve how agents discover decisions, risks, assumptions, and history

当用户提出以下需求时使用本技能：

安装或落地使用
```
codecontext
```
更新代码仓库的
```
AGENTS.md
```
或关于
```
@context
```
的Agent使用指引
审计项目当前的
```
codecontext
```
配置情况
协调解决codecontext工具和代码仓库说明不一致的问题
优化Agent发现决策、风险、假设和开发历史的方式

Outcome

预期结果

By the end of this workflow, the repo should have:

a clear
```
AGENTS.md
```
section for
```
codecontext
```
a sane CLI workflow for agents
the right enforcement surface for the repo's languages and toolchain
no misleading guidance about structured sidecar docs

完成本工作流后，代码仓库应当具备：

```
AGENTS.md
```
中清晰的
```
codecontext
```
使用说明板块
合理的Agent CLI使用工作流
适配代码仓库语言和工具链的正确校验规则
不存在关于结构化附属文档的误导性指引

Workflow

工作流

1. Audit the current state

1. 审计当前状态

Inspect:

package manager and workspace layout
whether the repo already depends on
```
@recallnet/codecontext-cli
```
whether the repo already depends on
```
@recallnet/codecontext-eslint-plugin
```
whether the repo already has Python, Go, Rust, or other language-native
whether the repo already has Python, Go, Ruby, Rust, or other language-native checkers where
```
codecontext
```
enforcement belongs
whether ESLint is present and where its shared config lives
whether
```
AGENTS.md
```
exists at repo root and in subtrees/worktrees
whether existing agent docs already mention
```
@context
```
,
```
codecontext
```
, ADRs,
```
contexts/
```
, or decision logs

Look for the two common failure modes:

tool installed, but no agent workflow or guidance
guidance exists, but it is stale, contradictory, or points to a policy that does not exist

检查以下内容：

包管理器和工作区结构
代码仓库是否已经依赖
```
@recallnet/codecontext-cli
```
代码仓库是否已经依赖
```
@recallnet/codecontext-eslint-plugin
```
代码仓库是否已经有Python、Go、Rust或其他语言原生的校验工具
代码仓库是否已经有Python、Go、Ruby、Rust或其他语言原生的、应当集成
```
codecontext
```
校验能力的检查工具
是否存在ESLint，以及其共享配置的存放位置
代码仓库根目录和子树/工作树中是否存在
```
AGENTS.md
```
现有Agent文档是否已经提及
```
@context
```
、
```
codecontext
```
、ADR、
```
contexts/
```
或决策日志

排查两种常见的故障模式：

工具已安装，但没有对应的Agent工作流或使用指引
存在使用指引，但内容过时、相互矛盾，或是指向不存在的规则

2. Decide the installation surface

2. 确定安装范围

Install the minimum useful surface:

@recallnet/codecontext-cli

when agents should run

--scope

--diff

, or

--report

```
@recallnet/codecontext-eslint-plugin
```
when the repo uses ESLint and wants comment validation
a language-native checker or analyzer when the repo's main enforcement surface is Python, Go, Rust, or something else outside ESLint
```
@recallnet/codecontext-parser
```
only if the repo has custom code that imports parser APIs directly

Do not add packages the repo is not going to use.

安装最小可用的工具集：

当Agent需要运行

--scope

、

--diff

或

--report

命令时，安装

@recallnet/codecontext-cli

当代码仓库使用ESLint且需要注释校验能力时，安装
```
@recallnet/codecontext-eslint-plugin
```
当代码仓库的主要校验层是Python、Go、Rust或其他ESLint之外的技术栈时，安装对应语言原生的检查器或分析器
仅当代码仓库有直接导入解析器API的自定义代码时，才安装
```
@recallnet/codecontext-parser
```

不要添加代码仓库不会用到的依赖包。

3. Fix

AGENTS.md

before or alongside package changes

3. 在修改依赖包之前或同时修复

AGENTS.md

codecontext

setup is incomplete without agent instructions.

Every repo-level

AGENTS.md

section should cover:

what
```
@context
```
is for
when annotations are required
a small preferred taxonomy
the pre-edit and post-edit workflow
what refs are and are not
anti-patterns

If subtree

AGENTS.md

files point to a repo-level policy, make sure that policy actually exists.

如果没有Agent使用说明，

codecontext

的配置就是不完整的。

每个代码仓库级别的

AGENTS.md

相关板块都应当涵盖：

```
@context
```
的用途
何时必须添加注解
推荐的小规模分类体系
编辑前和编辑后的工作流
引用的定义和使用规范
反模式说明

如果子树的

AGENTS.md

文件指向了仓库级别的规则，请确保该规则真实存在。

Recommended

AGENTS.md

contract

推荐的

AGENTS.md

契约

Keep it short. A good section usually fits in 8-14 bullets.

Use something close to this:

- **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.

Adjust the taxonomy only if the repo clearly needs more than the baseline (

decision

risk

requirement

history

). Add extra categories sparingly.

保持内容简洁，一个好的说明板块通常只需要8-14条要点。

可以参考以下模板：

- **codecontext**：对非显而易见的、高价值的逻辑添加行内`@context`注解，避免后续编辑误删相关信息。
  - 必须添加注解的场景：
    - 关键决策逻辑和不变量
    - 安全相关的行为和来之不易的经验教训
    - 外部集成的特殊情况和契约不匹配问题
    - 回归防护说明，解释为什么更简单的改动不可行
  - 推荐的注解类型：`@context decision`、`@context risk`、`@context requirement`、`@context history`
  - 注解内容要简短明确：说明当前的事实、重要性，以及改动后会出现什么问题
  - 必要时使用`{@link ...}`指向支持材料，但引用仅作为指向仓库文件或文档的指针，不要要求使用任何特殊的文档schema。
  - 编辑关键文件前运行：
    `npx @recallnet/codecontext-cli --scope <file>`
  - 编辑完成后运行：
    `npx @recallnet/codecontext-cli --diff HEAD <file>`
  - 在大型仓库中进行整体概览时运行：
    `npx @recallnet/codecontext-cli --report`
  - 不要将`@context`用于显而易见的说明、重复的ADR内容或是通用注释。

仅当代码仓库明确需要超出基线（

decision

、

risk

、

requirement

、

history

）的分类时，再调整分类体系，谨慎添加额外类别。

Guidance for repos with ADRs or large docs trees

对使用ADR或大型文档树的仓库的指引

If the repo already uses ADRs, plans, runbooks, or architecture docs:

keep
```
@context
```
as the inline agent-facing layer
treat refs as optional expansion targets
do not tell agents to browse the entire docs tree by default
do not mirror whole ADRs inline

The correct model is:

```
@context
```
carries the structured local signal
refs point to arbitrary supporting material
agents expand refs only when needed

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

保留
```
@context
```
作为面向Agent的行内信息层
将引用视为可选的扩展信息入口
不要默认要求Agent浏览整个文档树
不要将完整的ADR内容复制到行内注解中

正确的使用模式是：

```
@context
```
承载结构化的局部信号
引用指向任意的支持材料
Agent仅在需要时展开查看引用内容

Refs policy

引用规则

Be explicit:

refs are allowed to point to
```
.md
```
,
```
.html
```
,
```
.txt
```
, diagrams, exports, or other repo artifacts
refs are not required on every annotation
refs should not impose a schema on the target file

Do not write guidance that implies:

```
.ctx.md
```
is required
frontmatter is required
the linked file must be machine-parseable

明确说明以下规则：

允许引用指向
```
.md
```
、
```
.html
```
、
```
.txt
```
、流程图、导出文件或其他仓库产物
不是每个注解都必须添加引用
引用不应对目标文件施加schema要求

不要编写暗示以下要求的指引：

必须使用
```
.ctx.md
```
必须有frontmatter
链接的文件必须是机器可解析的

CLI workflow guidance

CLI工作流指引

Recommend these commands in agent docs when the CLI is installed:

bash

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

Use

--report

for repo orientation and decision review. Use

--scope

and

--diff

around concrete edits.

当安装了CLI后，在Agent文档中推荐以下命令：

bash

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

用于具体的编辑操作前后。

Enforcement guidance

校验规则指引

If the repo already has a shared ESLint config, integrate the plugin there. Prefer enforcing syntax and stale/invalid ref checks centrally rather than telling agents to self-police.

If the repo does not use ESLint, do not force it just for

codecontext

. Prefer the native enforcement surface for the repo's actual stack:

Python repo: native checker or PyPI-distributed tool
Go repo: analyzer /
```
golangci-lint
```
integration
Ruby repo: native checker gem or RuboCop-style integration
Rust repo: crate / Clippy-style integration
mixed or tool-agnostic repo: CLI workflow may be enough initially

The important question is not "did we install the ESLint plugin?" It is "what actually enforces

@context

correctness in this ecosystem?"

如果代码仓库已经有共享的ESLint配置，将插件集成到该配置中。优先在中心层面统一校验语法和过时/无效引用，而非要求Agent自行检查。

如果代码仓库不使用ESLint，不要仅为了

codecontext

强制引入ESLint。优先适配代码仓库实际技术栈的原生校验层：

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

核心问题不是“我们有没有安装ESLint插件”，而是“在当前技术栈中，什么工具能真正校验

@context

的正确性？”

What to look for in a review

审查要点

Flag these as setup defects:

child
```
AGENTS.md
```
files pointing to a missing repo policy
instructions that mention
```
@context
```
but give no workflow
workflow guidance that ignores
```
--report
```
in large repos
guidance that treats linked docs as required structured sidecars
package installs without corresponding agent documentation
documentation that tells agents to read giant ADR/doc trees by default

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

子目录的
```
AGENTS.md
```
文件指向不存在的仓库级规则
说明中提到了
```
@context
```
但没有给出对应的工作流
大型仓库的工作流指引中没有提及
```
--report
```
指引中将链接的文档视为必填的结构化附属文件
安装了依赖包但没有对应的Agent使用文档
文档默认要求Agent阅读庞大的ADR/文档树

Delivery

交付要求

When you finish setup or audit work:

state what was installed or changed
call out any stale or contradictory
```
AGENTS.md
```
guidance you fixed
mention any remaining gaps
if you did not install an enforcement surface, explain why

完成配置或审计工作后：

说明安装或修改的内容
指出你修复的所有过时或矛盾的
```
AGENTS.md
```
指引
说明仍存在的待完善缺口
如果你没有安装校验层，解释原因

Default recommendation

默认推荐

If the repo has no existing

codecontext

guidance, prefer creating a

codecontext-setup

section in the root

AGENTS.md

rather than scattering instructions across multiple child docs first.

如果代码仓库没有现有的

codecontext

指引，优先在根目录的

AGENTS.md

中创建一个

codecontext-setup

板块，而不是一开始就把说明分散到多个子文档中。

codecontext-setup

Original

Translation

Codecontext Setup

Codecontext设置

When to use

何时使用

Outcome

预期结果

Workflow

工作流

1. Audit the current state

1. 审计当前状态

2. Decide the installation surface

2. 确定安装范围

3. Fix
`AGENTS.md`
before or alongside package changes

3. 在修改依赖包之前或同时修复
`AGENTS.md`

Recommended
`AGENTS.md`
contract

推荐的
`AGENTS.md`
契约

Guidance for repos with ADRs or large docs trees

对使用ADR或大型文档树的仓库的指引

Refs policy

引用规则

CLI workflow guidance

CLI工作流指引

Enforcement guidance

校验规则指引

What to look for in a review

审查要点

Delivery

交付要求

Default recommendation

默认推荐

codecontext-setup

Original

Translation

Codecontext Setup

Codecontext设置

When to use

何时使用

Outcome

预期结果

Workflow

工作流

1. Audit the current state

1. 审计当前状态

2. Decide the installation surface

2. 确定安装范围

3. Fix AGENTS.md before or alongside package changes

3. 在修改依赖包之前或同时修复AGENTS.md

Recommended AGENTS.md contract

推荐的AGENTS.md契约

Guidance for repos with ADRs or large docs trees

对使用ADR或大型文档树的仓库的指引

Refs policy

引用规则

CLI workflow guidance

CLI工作流指引

Enforcement guidance

校验规则指引

What to look for in a review

审查要点

Delivery

交付要求

Default recommendation

默认推荐

3. Fix
`AGENTS.md`
before or alongside package changes

3. 在修改依赖包之前或同时修复
`AGENTS.md`

Recommended
`AGENTS.md`
contract

推荐的
`AGENTS.md`
契约