From 87fc0a6a669bb635afa4104a75966559424c45af Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 08:52:59 +0000 Subject: [PATCH 1/3] feat(agents): move ground rules into a shared AGENTS.md AGENTS.md is what most coding agents look for, so keeping one neutral copy avoids a per-vendor duplicate that drifts. Claude Code only reads CLAUDE.md, so bootstrap symlinks ~/.claude/CLAUDE.md to this file. --- bootstrap | 9 +++++++-- misc-configs/{claude/CLAUDE.md => agents/AGENTS.md} | 12 +++++++++--- 2 files changed, 16 insertions(+), 5 deletions(-) rename misc-configs/{claude/CLAUDE.md => agents/AGENTS.md} (95%) diff --git a/bootstrap b/bootstrap index a9dcb302..1cf40703 100755 --- a/bootstrap +++ b/bootstrap @@ -46,9 +46,14 @@ ln -sf ~/dotfiles/misc-configs/lazygit/config.yml .config/lazygit/config.yml # -- Git -- ln -sf ~/dotfiles/gitignore_global .gitignore_global -# -- Claude Code -- +# -- Agent instructions -- +# Ground rules live in an agent-neutral AGENTS.md (https://agents.md) so any +# coding agent can read the same file. Claude Code reads CLAUDE.md and not +# AGENTS.md, so it gets a symlink named after what it looks for. mkdir -p .claude -ln -sf ~/dotfiles/misc-configs/claude/CLAUDE.md .claude/CLAUDE.md +ln -sf ~/dotfiles/misc-configs/agents/AGENTS.md .claude/CLAUDE.md + +# -- Claude Code -- # Linked individually (not the whole dir) to allow third-party skills alongside ours. mkdir -p .claude/skills for skill in ~/dotfiles/misc-configs/claude/skills/*/; do diff --git a/misc-configs/claude/CLAUDE.md b/misc-configs/agents/AGENTS.md similarity index 95% rename from misc-configs/claude/CLAUDE.md rename to misc-configs/agents/AGENTS.md index 9ced42f9..03090f6e 100644 --- a/misc-configs/claude/CLAUDE.md +++ b/misc-configs/agents/AGENTS.md @@ -1,5 +1,11 @@ # Ground Rules + + ## Attribution -- If a human committed it, it's their responsibility, not Claude's. -- Claude is a collaborative partner tool, similar to a rubber duck that can code. -- Never add Claude/Anthropic attribution (e.g. "Generated with Claude Code", "🤖", "Co-Authored-By") to any output: commits, PRs, issues, comments, or any other content. +- If a human committed it, it's their responsibility, not the agent's. +- An agent is a collaborative partner tool, similar to a rubber duck that can code. +- Never add agent attribution (e.g. "Generated with Claude Code", "🤖", "Co-Authored-By") to any output: commits, PRs, issues, comments, or any other content. ## Tooling From 7d56606ad83463f2389bd549c37b318df1146f5b Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 08:52:59 +0000 Subject: [PATCH 2/3] docs(agents): split example project instructions into AGENTS.md Shows the pattern for a project: shared rules in AGENTS.md, pulled into CLAUDE.md with an @AGENTS.md import, with Claude-only rules below it. --- example-configs/AGENTS.md | 15 +++++++++++++++ example-configs/CLAUDE.md | 18 ++++++++---------- 2 files changed, 23 insertions(+), 10 deletions(-) create mode 100644 example-configs/AGENTS.md diff --git a/example-configs/AGENTS.md b/example-configs/AGENTS.md new file mode 100644 index 00000000..51ea7002 --- /dev/null +++ b/example-configs/AGENTS.md @@ -0,0 +1,15 @@ +# AGENTS.md + +## CRITICAL REMINDERS + +- **ALWAYS** use the task runner (Taskfile) to execute any commands related to this project. + +## Key Technologies + +- **Task Runner**: Taskfile (Taskfile.yaml) + +## Environment Variables + +- When adding environment variables, prefix them with `MY_APP_` to avoid collisions with system and third-party variables. + - `MY_APP_` will be replaced with this project's actual prefix. + - Use `SCREAMING_SNAKE_CASE`: `MY_APP_DATABASE_URL`, not `my_app-databaseUrl`. diff --git a/example-configs/CLAUDE.md b/example-configs/CLAUDE.md index 7a65b0f9..0f4f3c74 100644 --- a/example-configs/CLAUDE.md +++ b/example-configs/CLAUDE.md @@ -1,15 +1,13 @@ # CLAUDE.md -## CRITICAL REMINDERS + -- **ALWAYS** use the task runner (Taskfile) to execute any commands related to this project. +@AGENTS.md -## Key Technologies +## Claude Code -- **Task Runner**: Taskfile (Taskfile.yaml) - -## Environment Variables - -- When adding environment variables, prefix them with `MY_APP_` to avoid collisions with system and third-party variables. - - `MY_APP_` will be replaced with this project's actual prefix. - - Use `SCREAMING_SNAKE_CASE`: `MY_APP_DATABASE_URL`, not `my_app-databaseUrl`. +- Use plan mode for changes that span more than one package. From 305f250070774b767fa5781479f0a07fdf68cd5c Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 08:52:59 +0000 Subject: [PATCH 3/3] docs: explain the AGENTS.md setup --- FAQ.md | 12 ++++++++++++ example-configs/README.md | 6 ++++++ 2 files changed, 18 insertions(+) diff --git a/FAQ.md b/FAQ.md index c52c8865..87724683 100644 --- a/FAQ.md +++ b/FAQ.md @@ -105,6 +105,18 @@ Load: nvim -i custom.shada ``` +## Agents + +### Why keep the ground rules in `AGENTS.md`? + +[AGENTS.md](https://agents.md) is the file most coding agents already look for, so a +single copy in `misc-configs/agents/AGENTS.md` covers all of them. A per-vendor copy of +the same rules would drift the moment one of them is edited and the other isn't. + +Claude Code is the exception: it reads `CLAUDE.md`, not `AGENTS.md`. `bootstrap` handles +that by symlinking `~/.claude/CLAUDE.md` to the shared file. Projects do the same with an +`@AGENTS.md` import, see `example-configs/CLAUDE.md`. + ## Claude ### Why disable `autoMemoryEnabled`? diff --git a/example-configs/README.md b/example-configs/README.md index 4d3fd534..da1a965e 100644 --- a/example-configs/README.md +++ b/example-configs/README.md @@ -8,3 +8,9 @@ Skills installed with the [`skills`](https://skills.sh) CLI are pinned in `skill npx skills update # update all npx skills update # update one ``` + +## Agent instructions + +Instructions shared by every agent go in `AGENTS.md`. `CLAUDE.md` pulls them in with an +`@AGENTS.md` import and adds only the Claude-specific rules below it, so there's one copy +of the shared rules instead of one per agent.