io.github.awalhadi由 GitHub 账号 awalhadi 发布v0.7.1更新于 Nov 3, 2026
面向AI编码代理的AGENTS.md与项目记忆，始终保持正确：规则会对照git进行检查
AI 翻译由 AI 模型根据下方的原文描述翻译，可能有误。
AGENTS.md and project memory for AI coding agents that stays correct: rules checked against git
RepoCanon 的本地 MCP 服务；无需登录；STDIO；10 个工具。
暂无 AI 概览：以下信息来自注册中心条目和服务本身。
Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。
参照 仓库 中的启动说明。
Verified AGENTS.md and project memory for AI coding agents. One small .ai/ folder tells Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI, Windsurf and Cline how your project works, and git checks that it is still true.
[npm version] [npm downloads] [license: MIT] [node] [dependencies: 0] [MCP server]
Sponsored by Framimo — turn any clip into GIF, WebP, AVIF or MP4, right in your browser.
In 30 seconds
AGENTS.md + .ai/) that every AI coding agent reads: the rules, decisions and gotchas your code can't show.CLAUDE.md and rules files rot silently. Nobody notices when they stop matching the code..cursor/rules, Copilot instructions, GEMINI.md, .windsurfrules, .clinerules…RepoCanon keeps one knowledge layer (AGENTS.md + .ai/), points every tool you use at it, and uses git to tell you which docs went stale after a code change. It runs locally, calls no LLM and has zero dependencies.
Requires Node.js 18+ and a git repository.
Then let your agent fill the docs. Either:
npx repocanon setup, details): tell your agent "Fill the RepoCanon docs". It calls rc_prepare_fill and writes .ai/*.md itself.npx repocanon prompt fill and paste the output into your agent.Finally, check the result and commit:
doctor showsEvery command prints the same shape: a header, rows, a one-line verdict, then Next: the exact commands to run. Symbols always come with a word, so the output also works without colour (NO_COLOR=1, --no-color, CI logs, screen readers).
Every command has --help with options and examples: npx repocanon status --help. --json and --format=github give machine-readable output for scripts and CI.
adopt reads CLAUDE.md, GEMINI.md, .windsurfrules, .clinerules, .github/copilot-instructions.md, .cursorrules, always-on .cursor/rules/*.mdc, repo-wide Copilot instructions and Cline's memory-bank/. It routes each section to the right doc (glossary → DOMAIN, decisions → DECISIONS, progress → STATE, overview → PROJECT, the rest → CONVENTIONS), drops directory trees, dependency lists, pasted code and secrets, and tells you how many tokens that saved. Rules that are already scoped to certain files stay where they are. Re-running skips what was already imported; --move never touches a file with uncommitted changes.
Docs are a semantic index, never a copy of the code. When docs and code disagree, code wins and the doc gets fixed.
init opens a picker for the AI tools that should read the knowledge layer. AGENTS.md is always written; each tool you pick gets a small pointer file:
init reopens the picker with your saved choice and marks each tool set up or detected. If nothing changed it prints Up to date.init offers to remove its RepoCanon block. Only that block goes: your own text stays, and a file is deleted only if nothing else is in it.--targets=claude,cursor, --targets=all or --targets=none; --yes keeps the saved choice; --prune removes blocks of tools you no longer select.npx repocanon rules turns each filled module doc into rule files that a tool loads only while the agent edits that module's files — no tool call, no extra tokens anywhere else:
.ai/modules/<module>.md stays the single source. Generated files say so in their header; edit the doc, then run rules again.init. Nested AGENTS.md pointers are off by default; turn them on with "nestedAgents": true in .repocanon.json.init runs rules for you, doctor warns when the files are out of date, and rules --check fails CI until they're regenerated.npx repocanon skills (also run by init) writes an Agent Skill that tells agents how to verify a change in this repo: .ai/skills/rc-verify-change/SKILL.md. Only its one-line description sits in the agent's context; the body loads when the agent is about to say "done".
package.json / composer.json scripts (run with your package manager), Makefile, justfile, Taskfile.yml, and the run: steps of .github/workflows/*.yml or .gitlab-ci.yml. Each one says where it was found, duplicates are merged, and steps run in order: format → lint → typecheck → test (an aggregate make check comes first)..ai/skills/ is the one place to edit. Change the generated skill and RepoCanon stops regenerating it; add your own .ai/skills/<name>/SKILL.md and it is copied out too.Copies are written only for the tools you chose, carry a "Generated by RepoCanon" header, and are removed when you deselect the tool. A skill of the same name that RepoCanon didn't write is never overwritten. Skills with an invalid name (lowercase, hyphens, must match the folder), a missing description or a secret are not copied, and doctor says why. Windsurf and Cline don't read skills folders yet.
RepoCanon reads pnpm, npm, yarn and bun workspaces, lerna, nx (project.json), turbo, go.work, Cargo workspaces and uv workspaces. Then:
packages/ui (@acme/ui) → ui.apps/web (Next.js) → web-billing, web-pricing; apps/api (NestJS) → api-users, api-billing. Otherwise the app is one module.apps-web, packages-web)..ai/INDEX.md gets a Workspace table (package, path, app or package, stack), and the fill brief says it's a monorepo. To split differently, set moduleRoots or modules, or a fixed preset, in .repocanon.json; any of those turns the workspace split off.
A plain rule in a doc is only as fresh as the whole doc. Annotate the rules that matter, and RepoCanon checks each one on its own:
repocanon claims lists every claim with its tier and state. It exits 1 on a broken claim, or on a stale one with --ci.doctor reports broken claims as errors and stale ones as warnings.rc_context and the edit-time hook mark a stale claim on its doc, even when the doc as a whole looks fresh.stamp <doc> (and rc_stamp) lock the claims of the docs it verifies. A claim whose code has uncommitted changes isn't locked.After you or your agent change code:
The stamp edits verified_at (and verified_by: human) in that doc; it rides along with your next commit.
After a code change, status and sync show what drifted:
With MCP connected, just say "update the context docs": the agent calls rc_sync_report, edits the docs, records decisions and progress with rc_propose_adr / rc_checkpoint_state, stamps what it re-checked with rc_stamp and finishes with rc_verify. Agent stamps write verified_by: agent: the doc counts as fresh, but status shows fresh (agent) and doctor and the PR report list it so a human can re-check. A human repocanon stamp replaces it.
Optional: npx repocanon hook installs a pre-commit hook. It warns when code changes without any .ai/ update (never blocks), and blocks a commit that would add an API key, token or password to AGENTS.md or .ai/ docs (git commit --no-verify overrides). The secret check needs RepoCanon installed locally (npm i -D repocanon) or globally.
repocanon mcp is a stdio Model Context Protocol server. Agents use it to fetch a budgeted context pack instead of scanning the repo, and to update the docs without copy-paste.
Let RepoCanon write the config:
setup adds only its own repocanon entry: other servers and settings in the file stay as they are, and re-running it changes nothing. A file that isn't plain JSON (for example .vscode/mcp.json with comments) is left alone and you get the block to paste. Tools with a global config (Windsurf, Cline, Codex) get a ready-to-paste snippet with your project path.
Or add it by hand. Most tools take this block:
The server works on the folder it starts in. Global configs (Windsurf, Cline) usually start outside your project, so add the path: "args": ["-y", "repocanon", "mcp", "--root=/abs/path/to/project"].
Write tools validate before touching a file: one line per field, length limits, and no secrets, pasted code, trees or dependency lists. A refused write changes nothing. Every tool carries MCP annotations (readOnlyHint), so clients can auto-approve the read-only ones.
The plugin connects Claude Code to the knowledge layer with one install, and keeps the docs current while Claude works:
The hooks do nothing in projects without an .ai/ folder. They run npx repocanon, so the first session downloads it once.
The GitHub Action checks every pull request, annotates problems on the changed lines, and keeps one summary comment up to date:
The comment looks like this:
RepoCanon: ⚠️ 1 module(s) changed without their docs
Freshness 82/100 · 1 stale, 0 broken, 2 unverified
Only meaningful code changes count: edits to tests, prose docs and lockfiles, and whitespace-only changes, never make a doc stale. Add your own patterns with driftIgnore, or set "drift": "all" to count every change.
Without the action — the same checks as plain commands:
Global flags: --root=<dir> runs against another folder; --version; --help.
.repocanon.json (created by init):
preset: auto (from the detected stack) or one of laravel nextjs nuxt react vue nestjs node fastapi django rails go tauri. Presets merge one domain across layers:
A name has to appear in at least two layers to become a module, so a lone User.php or health.py doesn't.
moduleRoots: extra folders whose child folders are modules.
modules: explicit module → paths; overrides a detected module with the same name.
exclude: path prefixes ignored everywhere.
targets: the AI tools init set up (managed by the picker).
nestedAgents: also write a pointer AGENTS.md into each module folder (default false).
entryDigest: keep a digest of .ai/CONVENTIONS.md and .ai/DECISIONS.md (one line per decision, about 700 tokens at most) in the AGENTS.md block (default true). Agents reliably follow what is in their entry file and often skip a pointer to another file; false leaves only the pointer. rules regenerates the digest, and doctor, rules --check and the PR report flag it when it falls behind.
driftIgnore: extra paths whose changes never make a doc stale (folder prefixes ending in /, * and ** globs). Tests, prose docs, lockfiles and whitespace-only edits are always ignored; "drift": "all" turns that off.
Does project knowledge help, and does RepoCanon deliver it better than a hand-written AGENTS.md? Claude Code (claude-sonnet-5-5, CLI 2.1.178) ran 8 tasks in JavaScript, Python, PHP and Rust projects, 5 times under each of 4 conditions: 160 runs in all, on 2026-10-27. Each task touches project rules the code doesn't reveal. A run passes when hidden tests and rule checks pass.
What this shows, and what it doesn't:
AGENTS.md, and it cost about 1.5× more. Its agents read 6+ .ai/ docs per run and made about twice as many edits, following the Definition of Done in AGENTS.md. Both knowledge formats hit 100%, so this benchmark can't separate them on correctness.Method, tasks and how to rerun it: bench/README.md. Raw results: bench/results/2026-10-27/.
Each of 4 drift tasks verifies the docs, then commits a change to one value they describe (a fee rate, a default, a cap, an error code). Hidden tests expect the code's new value. 12 runs, one per task and condition, on 2026-10-28:
claude-sonnet-5-5 trusts the code without being told. This design can't show a benefit from staleness warnings, so the planned 60-run version was not run.Raw results: bench/results/2026-10-28-drift/.
The pilot's tool counts traced the extra cost to two instructions in AGENTS.md: a read order (5–10 knowledge-doc reads per run) and a mandatory Definition of Done (9–15 edits). 0.7 replaced both: the entry lists only docs that have content, and asks for doc edits only when a rule, flow or decision changed. 44 runs on 2026-10-28, claude-sonnet-5-5:
AGENTS.md never does that work, so this is the price of docs that stay current, and the target of ≤1.2× was not met.Raw results: bench/results/2026-10-28-cost/ and 2026-10-28-cost2/.
node-cancel-xdrift: the docs say cancelOrder restocks and the warehouse listeners only record shipments. A later commit moves restocking into the warehouse listener on order.cancelled. Following the doc restocks twice. Three rounds of 9 runs each (3 per condition): the drift as the newest commit, then buried under 12 unrelated commits, then the same with a grader check of the docs afterwards.
AGENTS.md agents never did: the doc that misled nobody this time is still wrong for the next agent and for people. Earlier rounds, judged from the agents' own summaries, agree (RepoCanon 12/12, AGENTS.md 2/6).AGENTS.md.Repo packers show an agent what the code is. RepoCanon records what the code can't say — rules, decisions, boundaries — and tells you when that record goes stale.
Does it call an LLM or upload my code? No. RepoCanon never makes network calls. Your own agent reads and writes the docs.
What if an agent pastes a secret into the docs? doctor reports it as an error (so doctor --ci fails), npx repocanon secrets lists it masked, and the pre-commit hook blocks the commit. Mark a known false positive with <!-- repocanon:allow-secret --> on that line.
What if someone plants instructions for the agent? A pull request, a dependency or a build step can add text to AGENTS.md, .ai/ or CLAUDE.md that agents will follow. doctor fails on hidden Unicode (bidi overrides, zero-width marks, tag characters), "ignore previous instructions"-style overrides, rules that hide work from the user, fake <system> markers and curl … | sh, and warns about instruction files git doesn't track. MCP writes refuse the same text, and the pre-commit hook blocks it. Mark intended text with <!-- repocanon:allow-instruction -->.
Does it work with ChatGPT? OpenAI Codex reads AGENTS.md natively. ChatGPT in the browser can't see your repo, but npx repocanon context "your task" prints a pack you can paste.
Will it overwrite my CLAUDE.md or other rules files? No. It adds or updates one clearly marked block and leaves the rest of the file alone. Core docs in .ai/ are only replaced with init --force.
What about monorepos? Map packages with moduleRoots or modules today. Per-package knowledge layers are on the roadmap.
Can I use it as a library? Yes: require('repocanon') exposes the same functions the CLI uses. See CONTRIBUTING.
mcp-publisher publish): docs/PUBLISHING.mdFramimo — turn any clip into GIF, WebP, AVIF or MP4, right in your browser. Trim, crop, resize and compress animations; files are processed on your device.
Want to sponsor RepoCanon? Open an issue.
MIT © Md. A Awal Hadi
来源：README.md，提交 3a20e59
Context for a task
Budgeted context pack for a task: PROJECT + relevant module docs + DOMAIN/CONVENTIONS/STATE. Call this FIRST instead of scanning the repo. Docs that may not match the code carry a stale/broken/unverified label — trust the code there.
filesquerymax_tokensModule doc
Full knowledge doc for one module (purpose, invariants, flow, code map). Use when rc_context included only part of a module, or you need a module the task did not mention.
name必填Find owning module
Which module owns a repo-relative file path, and its doc. Use before editing a file whose module you do not know.
path必填Doc freshness
Freshness of every .ai doc (fresh/stale/broken/unverified) vs git, as JSON. For what changed and which docs to update, call rc_sync_report instead.
无需输入参数。
Brief for filling docs
Evidence-loaded brief for writing/filling the .ai/ knowledge docs (stack playbook, files to inspect, per-doc instructions). Call this, then write the .ai/*.md files yourself with your own file tools — do not ask the human to paste anything.
compactWhat changed since verify
What changed in the repo since each doc was last verified, and which docs likely need updating. Call this before rc_prepare_fill when the task is "update the docs after code changes", then write the affected .ai/*.md files yourself.
sinceRecord a decision
Record an architecture decision in its own file, .ai/decisions/<date>-<slug>.md (id D-<date>-<slug>), so parallel branches never conflict; the AGENTS.md rules digest is updated. Use when a task settled a choice future work must respect. One line per field; refused if it contains secrets, pasted code, trees or a duplicate title.
why必填title必填revisitdecision必填supersedesCheckpoint project state
Record where work stands in .ai/STATE.md so the next session can pick up: current focus, in-progress items, known issues, and one line for a significant change. Only the sections you pass change. This does NOT mark any doc verified.
focuschangein_progressknown_issuesMark docs verified
Mark docs verified against the current commit (verified_by: agent). Only after you have read the code and updated each doc so it matches; commit the code first — docs with uncommitted code changes are refused. Name every doc (module slug or core doc name such as STATE).
docs必填Am I done?
Am I done? Checks the knowledge layer: doctor errors and warnings, stale or broken docs, the Freshness Score. Ends with PASS or FAIL. Call before finishing a task that changed code or docs; pass docs to check only those.
docs已满足适用检查项的 90%
该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。
请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。
cd your-projectnpx repocanon init # pick your AI tools (↑/↓, space, enter)◆ repocanon init · shop
Stack Node.js, Express Tools Claude Code, Cursor
Files + .repocanon.json created + .ai/.gitignore created + .ai/INDEX.md created + .ai/PROJECT.md created + .ai/DOMAIN.md created + .ai/CONVENTIONS.md created + .ai/DECISIONS.md created + .ai/STATE.md created + .ai/prompts/update.md created + .ai/modules/_TEMPLATE.md created + AGENTS.md created + CLAUDE.md created + .cursor/rules/project.mdc created
Generated ✓ Module map 2 module(s) → .ai/INDEX.md · Scoped rules up to date ✓ Skills 3 file(s) updated: .ai/skills/rc-verify-change/SKILL.md, .claude/skills/rc-verify-change/SKILL.md, .agents/skills/rc-verify-change/SKILL.md
✓ Knowledge layer created
Next npx repocanon setup connect the MCP server to your tools npx repocanon prompt fill brief for your agent to fill the docs (or ask it over MCP) npx repocanon doctor check the resultnpx repocanon doctor # lint: size caps, TODOs, broken paths, token budget, content agents can infergit add -A && git commit -m "Add RepoCanon knowledge layer"npx repocanon stamp --all # mark the docs verified at that commitgit commit -am "Verify RepoCanon docs"◆ repocanon doctor · shop
Warnings (1) ! scoped rule files are out of date (2: .cursor/rules/rc-billing.mdc, AGENTS.md) — run: npx repocanon rules
Info (1) i 27 TODO placeholder(s) remain in .ai/ — run: repocanon prompt fill
Token budget Entry context (AGENTS + PROJECT + INDEX) ~662 tokens Whole repo source ~820 tokens Entry share of the repo 80.73% → estimates: word-aware for docs, bytes/4 for code
Freshness █████████░ 91/100
! 1 warning · 1 note(s)
Next npx repocanon prompt fill npx repocanon rules npx repocanon doctor run again after fixingnpx repocanon adopt --dry-run # preview: what goes where, what gets removednpx repocanon adopt # import into .ai/ (creates it if needed)git add -A && git commit -m "Adopt RepoCanon"npx repocanon adopt --move # originals become pointers, so tools stop reading two copiesAGENTS.md entry point every agent reads: commands, a digest of your rules and decisions, Definition of Done.ai/ PROJECT.md purpose, stack, boundaries INDEX.md path → module map (auto block refreshed by `analyze`) DOMAIN.md business rules, states, invariants, glossary CONVENTIONS.md coding style and patterns DECISIONS.md why things are built this way STATE.md current focus and recent changes modules/<name>.md one doc per module: purpose, invariants, flow, code map, gotchas.repocanon.json config (presets, modules, excludes, chosen tools)CLAUDE.md, .cursor/… small pointer files, only for the tools you pick## Invariants- Money is integer cents. <!-- rc: anchor=src/money/cents.js#toCents -->- Floats are rejected. <!-- rc: test=test/money.test.js#rejects floats -->- Never round twice.npx repocanon sync # which docs are stale, which files changed, what to inspect# your agent updates the affected .ai/*.md (or: npx repocanon prompt update → paste)git commit -am "Update billing + docs"npx repocanon stamp billing # mark only the docs you actually re-checked (code must be committed)◆ repocanon status · shop
✓ .ai/INDEX.md fresh 2 commit(s) since verify ✓ .ai/PROJECT.md fresh 2 commit(s) since verify ✓ .ai/DOMAIN.md fresh 2 commit(s) since verify ✓ .ai/CONVENTIONS.md fresh 2 commit(s) since verify ✓ .ai/DECISIONS.md fresh 2 commit(s) since verify ✓ .ai/STATE.md fresh 2 commit(s) since verify ✓ .ai/modules/auth.md fresh ! .ai/modules/billing.md stale 1 code file(s) changed since verify
Freshness █████████░ 91/100
! 1 stale doc(s) · 8 docs
Next npx repocanon sync what changed and which docs to update npx repocanon stamp <doc> after you re-checked a doc against the code◆ repocanon sync · shop
Docs to update (1) ! billing 1 file(s) changed since a1b2c3d src/modules/billing/refund.js inspect: git diff a1b2c3d -- src/modules/billing/
! 1 doc(s) to update · 1 up to date · HEAD a1b2c3d
Next update the docs above only where behaviour, rules or flow changed npx repocanon stamp billing after committing, for each doc you re-checkednpx repocanon setup # the tools you picked in initnpx repocanon setup cursor copilot◆ repocanon setup · shop
+ .mcp.json created · repocanon server added + .cursor/mcp.json created · repocanon server added
✓ MCP server registered in 2 config(s)
Next restart or reload your tool so it starts the server ask your agent: "use rc_context for this task" to check it works{ "mcpServers": { "repocanon": { "command": "npx", "args": ["-y", "repocanon", "mcp"] } }}/plugin marketplace add awalhadi/repo-canon/plugin install repocanon@repocanon# .github/workflows/repocanon.ymlname: repocanonon: [pull_request]permissions: contents: read pull-requests: write # for the summary commentjobs: docs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: { fetch-depth: 0 } # full history, so freshness can be computed - uses: actions/setup-node@v4 with: { node-version: 20 } - uses: awalhadi/[email protected] with: fail-on: error # error (default) | stale | never# .github/workflows/repocanon.ymlname: repocanonon: [pull_request]jobs: docs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: { fetch-depth: 0 } # full history, so verified_at commits resolve - uses: actions/setup-node@v4 with: { node-version: 20 } - run: npx -y repocanon doctor --ci # fails on errors; add --strict to fail on warnings too - run: npx -y repocanon status --ci # fails on stale or broken docs - run: npx -y repocanon rules --check # fails when scoped rule files are out of date{ "preset": "auto", "moduleRoots": ["src/domains"], "modules": { "checkout": ["app/Services/Checkout/", "app/Models/Order.php"] }, "exclude": ["legacy/", "vendor/"], "targets": ["claude", "cursor"], "nestedAgents": false, "driftIgnore": ["src/generated/", "*.snap"]}