← All posts

In a recent LinkedIn post, I reshared an article about the “plan mode trap” and expressed some thoughts on the topic. Continuing the thread, this is what explaining the domain looks like in practice

Planning doesn’t need to be comprehensive, just deliberate. Articulate the desired outcome, name the visible constraints, let your guardrails handle the rest. Similar to plan mode, but leaner and on your terms.

The agent doesn’t know your codebase, your dependencies, or your constraints, your spec and guardrails carry the domain context in before the first token is written

This is one piece of a larger agentic workflow I run daily, delegating fix, feature, and ticketing tasks across my projects. The reason it scales is that each handoff stays small and purposeful.

In my Laravel projects, I have my Claude.md point to a few different docs I use as guardrails. It might look like Laravel code best practices with caveats to address my use with other project dependencies like Livewire.

The basis of my planning system rides on these files.

project-root/
├── Claude.md
└── docs/
    ├── specs/
    │   └── feature-name.md
    └── best-practices/
        └── laravel.md

I heavily utilize a docs/specs/ directory in the project root where the plan I’ve iterated on becomes a spec in the /specs directory, before kicking off the development flow. Keeping the scope narrow keeps things on track, and a tight spec can go from handoff to the agent to a PR nice and quick.

With my specs and best practices in place, the PR review goes much more easily and would require minimal changes, if any, before merge.

Both can be gitignored if you’d rather keep planning artifacts and guardrails out of your repo. However, for a team environment, keeping Claude.md in version control means everyone contributing to the project benefits from the same context.

The same principle that guides my code guides my planning. Keep it simple, keep it tight.