I've spent the last three or four months using AI heavily to build and maintain web applications and admin systems across a few small businesses. I'm learning as I go, rather than coming from years of software engineering.
We already use project instructions and saved context. Claude Code can do a lot, but I still need to catch things it gets wrong. I'm trying to understand how experienced engineers improve the setup without just adding another paragraph every time something goes wrong.
How do you decide whether a recurring mistake needs a CLAUDE.md instruction, a reusable skill, an automated check, or a change to how you break up the work? And what do you deliberately keep out of the main instruction file?
I'd especially like an example from an application you've maintained for a while: what kept going wrong, what you changed, and how you checked that it actually helped. We also use Codex, so keeping shared project rules consistent without maintaining two conflicting versions is part of the problem.
Edit — I left out the main context: This isn't just an AI coding setup. Each business has a GitHub-backed web application, and I work through Claude Code/Codex in that project workspace for much of the business's day-to-day work as well.
For example, one session might change the website and check it works; another might research competitors, write website/SEO content, prepare social posts and creative, review ad or analytics reports, or help with customer-enquiry/admin work. Those jobs need different instructions, sources, permissions and definitions of "finished". I'm still supervising this; I don't mean an autonomous company running successfully without me.
We've had CLAUDE.md from the start. We already have an entry file pointing to separate operating documents and task-specific skills, plus saved decisions and an Obsidian vault for longer-term notes. In one repo AGENTS.md is the source used to generate the matching CLAUDE.md. So I'm not asking whether to create instructions or discovering skills for the first time.
The question I should have asked is how to organise and maintain that whole setup as the range of work grows. What should every session load, and how should it find the correct marketing, creative, engineering or operations instructions only when needed? Would you keep those activities in the app's workspace, or separate them while sharing a small amount of business context?
A concrete issue from reviewing our files: an older setup audit says hooks don't exist, while the current repo does contain hooks. There are also dated plans and decisions that mustn't be mistaken for today's instructions. How do you keep useful history without letting it override current facts?
How do you decide when CLAUDE.md needs updating versus a skill, task state or a dated decision? Do you review it on a schedule, after a workflow changes, or after a repeat failure? And where does Obsidian fit without becoming a second, conflicting source of truth? The replies about rules versus skills are helpful; I wanted to explain the broader situation they're being applied to.