| name | refactoring-agent-instructions |
| description | Refactors bloated agent instruction files (CLAUDE.md, AGENTS.md, COPILOT.md, .cursorrules, etc.)
to follow progressive disclosure — minimal root file linking to categorized files in guidelines/.
Use when agent instructions are too long, hard to maintain, contain contradictions, or need reorganization.
|
Refactoring Agent Instructions
Refactor bloated agent instruction files into a minimal root with linked category files in guidelines/.
Quick Start
"My CLAUDE.md is 500 lines and hard to maintain"
"Clean up these agent instructions"
"Reorganize my project's coding guidelines"
Example: Before and After
Before — Bloated CLAUDE.md (~200 lines, everything inline)
# CLAUDE.md
This is the Acme billing API, a Phoenix backend serving REST and GraphQL.
Run tests: mix test --warnings-as-errors
Run lint: mix credo --strict
Format: mix format
NEVER push directly to main. All changes go through PRs.
NEVER commit .env or secrets files.
Use 2-space indentation in all Elixir files.
Pipe chains should start with a raw value, not a function call.
Prefer pattern matching over conditional logic.
Module names must match directory structure.
Always add @moduledoc to public modules.
Use Ecto.Multi for operations touching 2+ tables.
Changesets must validate all user-facing input.
Keep schema fields alphabetized.
Tests go in test/ mirroring lib/ structure.
Use ExUnit.Case, not third-party test frameworks.
Prefer setup blocks over repeated build calls.
Name test files *_test.exs matching the module under test.
Minimum 80% coverage on payment modules.
Use feature/ prefix for branches.
Squash-merge all PRs.
Commit messages: imperative mood, 50-char subject, blank line, body.
Tag releases as vX.Y.Z.
After — Minimal root + category files
CLAUDE.md (18 lines)
# Acme Billing API
Phoenix backend for the Acme billing platform.
NEVER push directly to main
NEVER commit .env or secrets files
[]()
[]()
[]()
