agent-rules

Machine-wide disk / storage policy for AI coding agents, plus a fork-aware installer that injects it into every AI platform's rule file.

The problem it solves: C: is a system drive, not a dump. This puts a first-class rule in front of Claude Code, Codex CLI, Gemini CLI, OpenCode, Cursor (and any agent that reads their rule files) so none of them treats the user profile / system drive as a storage, cache, SDK, or download target — G: (the designated data drive) is the default.

AGENTS.md (root of this repo) is the master policy. It is written once and shipped to every platform by the installer. Updates are made in the master and synchronized by re-running the installer.

Why an installer instead of symlinks or manual copies

Each platform hard-codes its own rule-injection point and format — there is no cross-tool standard this machine could single-source from. Different agents also got redirected over time by third-party forks (reverse-engineered clones, routers, packaged variants). So the installer:

• resolves each platform's effective path (env-var redirects like CLAUDE_CONFIG_DIR / CODEX_HOME / XDG_CONFIG_HOME, Gemini's context.fileName, Codex's AGENTS.override.md shadowing);
• writes the merge-safe wrapper (never clobbers content the user already put in these files — user content is preserved below the injected block);
• backs up the target before writing; writes BOM-less UTF-8;
• is byte-level idempotent — re-running produces identical files;
• audit mode (-Verify) proves which path each platform will actually read, before you trust the injection.

Per-machine configuration — you are NOT a G: user

AGENTS.md is a template ({{DATA_DRIVE}}, {{REPOS_ROOT}}, {{DOWNLOADS_ROOT}}, {{TMP_ROOT}}, {{CACHES_ROOT}}, {{SMALL_THRESHOLD_MB}}, {{BIG_THRESHOLD_MB}}). No drive letter or path is hardcoded — every user's rules are rendered from their own config. The G: values you see in the example are the original author's machine, nothing more.

Config resolution, first match wins:

1. -Config <path> — explicit config file
2. ~/.config/agent-rules.json — machine config (auto-written on first real run)
3. auto-detect — largest non-system fixed drive (falls back to the system drive)

Copy agent-rules.config.example.json and edit, or run the interactive first-setup:

.\install-agent-rules.ps1 -Init          # per-machine setup wizard
.\install-agent-rules.ps1 -DataDrive D:  # one-off: switch the data drive
.\install-agent-rules.ps1 -Config .\my-agent-rules.config.json

Every injected file carries the applied config's SHA-256 + summary in its header, so -Verify can report config drift (config changed but not re-injected) instead of silently serving stale rules.

Supported platforms

Platform	Injection file	Protocol notes
Claude Code	~/.claude/CLAUDE.md	honors CLAUDE_CONFIG_DIR
Codex CLI	~/.codex/AGENTS.md	honors CODEX_HOME; AGENTS.override.md shadows it
Gemini CLI	~/.gemini/GEMINI.md	default; name overridable via context.fileName
OpenCode	~/.config/opencode/AGENTS.md	honors XDG_CONFIG_HOME
Cursor	~/.cursor/rules/*.mdc	.mdc + YAML frontmatter, alwaysApply: true

Engine-level adaptation details live in the "各平台加载协议适配" section of the master AGENTS.md.

Usage

# install / refresh all platforms (first run auto-detects your data drive)
.\install-agent-rules.ps1

# read-only audit: effective paths, injection status, config summary, drift, fork markers
.\install-agent-rules.ps1 -Verify

# preview (no writes, config not persisted either)
.\install-agent-rules.ps1 -DryRun

# skip some platforms
.\install-agent-rules.ps1 -Skip codex,cursor

# recover a corrupted wrapper (drops whatever was inside it)
.\install-agent-rules.ps1 -Force

# run the test suite (isolated temp home, touches nothing real)
.\test-install-agent-rules.ps1

Advanced: -Master <path> and -UserHome <path> override the master rules file and the target user home (used for machine-migration or CI checks). -CcbPath <path> points the fork audit at a CCB launcher that is neither on PATH nor in a conventional install dir (nothing about that path is assumed — resolution is -CcbPath → PATH → env-derived conventional dirs).

Safety model

• Merge, never clobber. First install leaves existing files alone and appends the policy block; later installs replace only their own block (bounded by BEGIN/END markers) and keep everything below it.
• Backup before write. <target>.inst-bak-<timestamp>.
• Corruption is loud. If a previous block is missing its END marker the installer refuses to guess and tells you to restore the backup or pass -Force.
• Idempotent. Repeated runs are byte-identical (verified by the test suite).
• Verified by tests. test-install-agent-rules.ps1 runs every behavior in an isolated temp home and is exercised by CI.

Third-party fork handling

The installer audits known adaptations on the machine (-Verify):

• CCB ("Claude Code Best", a reverse-engineered Claude Code clone) — verified against its source to read ~/.claude/CLAUDE.md like the official client; no extra step needed, but it is reported when present.
• Antigravity packaged Gemini variants — inherit the global GEMINI.md; reported unless a settings.json context.fileName override redirects them (which is then detected).
• claude-code-router — model routing only; does not relocate rule files.

Repository layout

AGENTS.md                          master policy (single source of truth)
install-agent-rules.ps1            the injector (see -Help)
test-install-agent-rules.ps1       behavior test suite (exit 0 = pass)
.github/workflows/test.yml         CI: lint + tests on Windows

License

MIT — see LICENSE.