Recently, I wrote about the distinction between rules and skills in Claude Code — when to use each, and what happens when you get it wrong. That post was about the first design decision. This one is about what happens when your configuration grows past that first decision and starts feeling like a codebase.
Because it is one.
Config Is Architecture
When I look at my Claude Code setup today, I see rules, skills, agents, memory files, hooks, and conventions spread across dozens of files in multiple directories. They have dependencies. They have loading strategies. They have token costs that compound. They interact in ways I did not always predict.
At some point I realized I was debugging my configuration the same way I debug software. A rule was interfering with a skill. An agent was loading context it did not need. A convention file had grown to 50 lines and was costing tokens in every conversation where it was irrelevant. These are not novel problems. They are the same problems that SOLID principles were designed to solve, just in a context nobody expected.
Single Responsibility
Each config artifact does one thing. A rule that handles both recognition and procedure is two things pretending to be one. I covered this in the previous post as the "split pattern" — separate the trigger from the instructions. The trigger is always loaded, lightweight, cheap. The instructions load only when needed.
This extends beyond rules. Consider a shipping workflow. You could build a single skill that finds the next task, implements it, runs tests, reviews the code, commits, pushes, and opens a PR. That is seven responsibilities in one file. Instead, I split it: /next finds and implements the task, /review self-checks against project conventions, /ship handles the test-commit-push-PR pipeline. Each skill does one thing. Each can be modified, replaced, or skipped without touching the others. If the review process changes, I edit /review. The shipping pipeline does not care.
Open-Closed
New capabilities should extend the system without modifying existing ones. When I needed a friction logging workflow, I created a new /friction-log skill. I did not edit the retrospective skill to accommodate friction capture, even though the two are related. When I needed a way to capture feature requests, I created /new-feature as its own skill rather than adding a "feature mode" to the task management system.
This sounds obvious written out. In practice, the temptation is strong to add "just one more section" to an existing file rather than create a new one. The cost of a new file feels higher than the cost of a longer file. This is usually not the case. A longer file is a file that does more things, loads more often than it should, and is harder to reason about when something breaks.
Interface Segregation
Do not load context that is not needed for the current task. This is the principle that pays the most immediate dividends with AI configuration.
Every line of config that loads into context competes with the actual task for the model's attention (excuse the oversimplification). I have watched output quality degrade because of what else was in context. A convention file about blog post formatting does not need to be present when I am debugging a build script. A detailed memory about project architecture does not need to load when I am writing a commit message.
Claude Code gives you the tools for this: path-scoped rules that only load when working with matching files, skills that load on demand, agents with restricted tool access. The question is whether you use them. The default is to make everything always-loaded because it feels safer. The cost is invisible until your context is full of instructions the model is not using, and the instructions it needs are competing for attention.
Dependency Inversion
Skills and agents should depend on abstractions, not on specific content. A skill that hardcodes a file path breaks when the file moves. A rule that references a specific memory entry breaks when the entry is updated. Instead, skills should search for what they need (query a database, read a directory, glob for files) and rules should describe patterns to recognize, not specific artifacts to find.
This is the one I see violated most often in AI configuration, including my own. It is tempting to write a rule that says "read projects/posts/ideas.md for blog topics." It is more robust to write one that says "check for a post ideas file in the posts project directory." The difference is small until you rename the file, move the directory, or restructure the project. Then it is the difference between a working system and a broken one.
The Payoff
None of this is groundbreaking if you have written software for any length of time. That is exactly the point. The principles that make code maintainable also make AI configuration maintainable, and for the same reasons. Config files grow. They develop dependencies. They interact in unexpected ways. They carry costs that are invisible until they compound.
The specific costs are different — token budgets instead of memory allocation, attention weight instead of CPU cycles — but the structural problems are identical. If you already think in SOLID when you write code, start thinking in SOLID when you write config. Your future self, debugging why the agent is not following a convention it was definitely told about, will thank you.
Top comments (0)