CLAUDE.md · git:20261117.ab63f92 · 2026-11-17 · sha256 a418811cea5a3e6d
CLAUDE.md git:20261117.ab63f92A
Immutable. This exact content never changes and is served at /api/v1/blob/a418811cea5a3e6d.
# CLAUDE.md @AGENTS.md ## Purpose `AGENTS.md`, imported above, holds the shared rules every coding agent follows. This file adds only what is specific to Claude Code: how to use the `.claude/` layer and how to manage Claude's context in this repo. Claude Code reads the import first, then the sections below. Without a `CLAUDE.md`, Claude Code would read `AGENTS.md` directly. This file exists to add Claude-only guidance on top of it. ## Working rules - Check the session-start result first. If it reports missing files, fix them before other work. - When you change a file in `.claude/`, check its counterpart in `.github/` (rules and instructions, agents, skills). Keep them aligned without forcing them to be identical. - For changes that touch more than one layer, use plan mode to outline the change before editing. ## Rules (`.claude/rules/`) - Use a rule for guidance that applies only to some files. Scope it with `paths` frontmatter. - A rule with `paths` loads when Claude reads or edits a matching file. A rule without `paths` loads in every session, like this file. - Example: `.claude/rules/repo-learning.md` applies only to teaching content such as `README.md`, `LEARN.md`, and `docs/**/*.md`. ## Subagents (`.claude/agents/`) - `learning-repo-maintainer` keeps teaching content aligned with the real files. Delegate to it for changes to `README.md`, `AGENTS.md`, `CLAUDE.md`, `.claude/`, `.github/`, or `skills/`. - It runs in its own context with its own tool list, and preloads the `validate-learning-repo` skill through its `skills` field. - Add a new subagent only for a repeated role with a clearly different focus or tool set. ## Skills (`.claude/skills/`) - `validate-learning-repo` audits whether the repo still matches what it teaches. Use it after structure or documentation changes. - Only a skill's `name` and `description` load at startup. The `SKILL.md` body loads when the skill is used, and files in `references/` load only when needed. - Claude Code does not load the shared skills in `skills/` automatically. When a user asks about them, read the relevant `SKILL.md` directly. ## Hooks and settings - `.claude/settings.json` is shared and committed. Its `SessionStart` hook runs `scripts/hooks/claude-session-context.sh`, which adds a one-line repo check result to the context. - Hook commands start with `bash`, so they work even when a script is not executable. - Keep hooks deterministic and fast. Judgment calls belong in rules, subagents, or skills. - Personal settings go in `.claude/settings.local.json`, which is gitignored. ## Context management - This file and `AGENTS.md` load in every session, so keep both short. Imports do not reduce context cost. - `LEARN.md` is long. Search for the module heading you need instead of reading the whole file. - Delegate broad audits to `learning-repo-maintainer` so the main conversation keeps only its summary. ## Boundaries - Do not copy shared rules from `AGENTS.md` into this file; change `AGENTS.md` instead. - Do not turn `CLAUDE.md` into a long reference manual; keep detailed task content in rules or skills. - Do not add hooks for subjective or long-running work.