From 06391a6247feb0947bab77c6f12de498b52dba07 Mon Sep 17 00:00:00 2001
From: Bastien Chanot <git@bchanot.fr>
Date: Sat, 4 Jul 2026 13:32:55 +0200
Subject: [PATCH] feat(rules): rules/ directory symlinked into ~/.claude like
 the other dirs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude Code loads modular rule files from ~/.claude/rules/ (user scope,
recursive, markdown, optional paths: frontmatter for lazy path-scoped
loading — stable, symlink-supported). The repo had no rules/ at all, so
the ctx7 setup had created ~/.claude/rules as a REAL directory outside
version control — invisible to the repo, unreproducible on a new machine.

- rules/README.md — doctrine: one rule per file; paths:-scoped extraction
  is the token win, always-on doctrine stays in CLAUDE.md
- link.sh — rules added to the symlinked-dirs loop
- .gitignore — rules/context7.md ignored (machine-owned: `ctx7 setup`
  (re)writes it, same treatment as skills/find-docs/)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpphkdTosUzokBDNG7PToS
---
 .gitignore      |  4 ++++
 link.sh         |  2 +-
 rules/README.md | 27 +++++++++++++++++++++++++++
 3 files changed, 32 insertions(+), 1 deletion(-)
 create mode 100644 rules/README.md

diff --git a/.gitignore b/.gitignore
index c3a222e..ecdd70d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -74,6 +74,10 @@ skills/find-skills
 # this repo's skills/). ctx7-managed and re-created on demand — not vendored here.
 skills/find-docs/
 
+# Context7 rule — (re)written by the same `ctx7 setup` into ~/.claude/rules (a
+# symlink to this repo's rules/). ctx7-managed — not vendored here.
+rules/context7.md
+
 # Staging area used by lib/toggle-external.sh when disabling a tool
 skills-disabled/
 
diff --git a/link.sh b/link.sh
index 8ae222a..20523d9 100644
--- a/link.sh
+++ b/link.sh
@@ -20,7 +20,7 @@ link_file() {
 link_file "$REPO/CLAUDE.md"     "$CLAUDE/CLAUDE.md"
 link_file "$REPO/settings.json" "$CLAUDE/settings.json"
 
-for item in hooks agents skills lib templates; do
+for item in hooks agents skills lib templates rules; do
   target="$CLAUDE/$item"
   if [ -L "$target" ]; then
     if [ "$(readlink "$target")" = "$REPO/$item" ]; then
diff --git a/rules/README.md b/rules/README.md
new file mode 100644
index 0000000..775b2df
--- /dev/null
+++ b/rules/README.md
@@ -0,0 +1,27 @@
+# rules/
+
+Modular instruction files loaded by Claude Code alongside `CLAUDE.md`.
+Symlinked to `~/.claude/rules` by `link.sh`, same model as `agents/`,
+`skills/`, `lib/`.
+
+## What belongs here
+
+One rule = one file = one concern. Candidates: instructions that are
+self-contained enough to live outside `CLAUDE.md`'s main flow, or that
+tooling generates/owns.
+
+Rules support an optional `paths:` YAML frontmatter (glob list). A rule
+WITH `paths` loads lazily — only when Claude reads a file matching a
+glob; a rule WITHOUT it loads at session start, same cost as CLAUDE.md.
+So: extract from CLAUDE.md only what can be path-scoped (the token win)
+or what is generated; always-on doctrine stays in CLAUDE.md.
+Docs: https://code.claude.com/docs/en/memory.md#path-specific-rules
+
+## Machine-owned files (gitignored, regenerated)
+
+- `context7.md` — written by `ctx7 setup --claude --cli`
+  (install-plugins.sh STEP ctx7). Not vendored: ctx7 owns its content
+  and rewrites it on setup; the repo would fight the generator. Same
+  treatment as `skills/find-docs/`.
+
+Hand-written rules ARE tracked — add them normally.