refactor: modularize CLAUDE.md into ~/.claude/rules/ with agent-team content separation

- Split monolithic CLAUDE.md into 7 focused rule files in rules/
- Remove agent-team specific content from global rules (subagent cost,
  model defaults, tier shortcuts) — already covered by orchestrate skill
- Add "prefer summaries over verbatim output" to orchestrate Step 8
- Update install.sh to symlink rules/ directory
- Trim CLAUDE.md to a minimal pointer since rules auto-load
This commit is contained in:
Bryan Ramos 2026-04-02 07:17:36 -04:00
parent f0cb4e840a
commit d2fdcbc731
11 changed files with 76 additions and 70 deletions

12
rules/01-session.md Normal file
View file

@ -0,0 +1,12 @@
# Session Behavior
- Treat each session as stateless — do not assume context from prior sessions
- The CLAUDE.md hierarchy is the only source of persistent context
- If something needs to carry forward across sessions, it belongs in a CLAUDE.md file, not in session memory
# Project Memory
- Project-specific memory lives in `.claude/memory/` at the project root
- Use `MEMORY.md` in that directory as the index (one line per entry pointing to a file)
- Memory files use frontmatter: `name`, `description`, `type` (user/feedback/project/reference)
- Commit `.claude/memory/` with the repo so memory persists across machines and sessions

6
rules/02-responses.md Normal file
View file

@ -0,0 +1,6 @@
# Responses & Explanations
- Be concise — lead with the action or answer, not the preamble
- Include just enough reasoning to explain *why* a decision was made, not a full walkthrough
- Skip trailing summaries ("Here's what I did...") — the diff speaks for itself
- No emojis unless explicitly asked

6
rules/03-git.md Normal file
View file

@ -0,0 +1,6 @@
# Commits & Git Workflow
- Make many small, tightly scoped commits — one logical change per commit
- Follow conventional commit format per the conventions skill
- Ask before pushing to remote or force-pushing
- Ask before opening PRs unless explicitly told to

17
rules/04-tools.md Normal file
View file

@ -0,0 +1,17 @@
# Tool & Approach Philosophy
- Prefer tools and solutions that are declarative and reproducible over imperative one-offs
- Portability across dev environments is a first-class concern — avoid hardcoding machine-specific paths or assumptions
- The right tool for the job is the right tool — no language/framework bias, but favor things that can be version-pinned and reproduced
# Parallelism
- Always parallelize independent work — tool calls, file reads, searches
- When a task has components that don't depend on each other, run them concurrently by default
- Sequential execution should be the exception, not the default
# Context Management
- Use subagents for exploratory reads and investigations to keep the main context clean
- Prefer scoped file reads (offset/limit) over reading entire large files
- When a task is complete or the topic shifts significantly, suggest /clear

10
rules/05-verification.md Normal file
View file

@ -0,0 +1,10 @@
# Verification
- After making changes, run relevant tests or build commands to verify correctness before reporting success
- If no tests exist for the changed code, say so rather than silently assuming it works
- Prefer running single targeted tests over the full suite unless asked otherwise
# When Things Go Wrong
- If an approach fails twice, stop and reassess rather than continuing to iterate
- Present the failure clearly and propose an alternative before proceeding

9
rules/06-nix.md Normal file
View file

@ -0,0 +1,9 @@
# Nix
- Nix is the preferred meta package manager on all systems — assume it is available even on non-NixOS Linux
- Always prefer a project-level `flake.nix` as the canonical way to define dev environments, build systems, and scripts
- Dev environments go in `devShells`, project scripts/tools go in `packages` or as `apps` within the flake
- Never suggest `apt`, `brew`, `pip install --user`, `npm install -g`, or other imperative global installs — reach for `nix shell`, `nix run`, or the project devshell instead
- Prefer `nix run` for one-off tool invocations and `nix develop` (or `direnv` + `use flake`) for persistent dev shells
- Binaries and tools introduced to a project should be pinned and run through Nix, not assumed to be on `$PATH` from the host
- Flakes are the preferred interface — avoid legacy `nix-env` or channel-based patterns

5
rules/07-research.md Normal file
View file

@ -0,0 +1,5 @@
# Research Before Acting
- Before implementing a solution, research it — read relevant documentation, search for existing patterns, check official sources
- Do not reason from first principles when documentation or prior art exists
- Prefer verified answers over confident guesses