Claude Code Gets Better When Your Project Gives It Structure — But Structure Is Only Half the Architecture
- Mark Kendall
- 1 day ago
- 8 min read
There is a point in almost every serious Claude Code implementation where the same realization hits:
The model is not the architecture.
Claude Code can reason, inspect a repository, write code, run tools, delegate work, and validate results. But if we simply drop an AI coding agent into a large repository and tell it to “figure it out,” we are leaving an enormous amount of engineering value on the table.
The project needs structure.
But there is an equally important second realization:
Project structure tells the agent where it is. Intent tells the agent where it needs to go.
That distinction changes everything.
A mature AI-assisted repository is not simply a collection of Markdown files, agents, hooks, skills, and MCP servers. It is an execution environment designed around intent, context, delegation, capabilities, and deterministic governance.
And once those pieces are separated by responsibility, the architecture becomes surprisingly clean.
The Project Is Part of the AI System
Traditional software architecture primarily organizes code for humans and deterministic runtime systems.
Agentic software introduces another consumer:
the reasoning system itself.
Claude needs to understand things such as:
What kind of repository is this?
What architecture does it follow?
What conventions are important?
What am I trying to accomplish right now?
What constraints cannot be violated?
What organizational procedures already exist?
What information should I retrieve?
What tools may I use?
What work should I delegate?
What must be validated before I declare success?
Those questions should not all be answered by one gigantic prompt.
They belong at different architectural layers.
That is where Claude Code’s project structure becomes powerful.
CLAUDE.md: Where Am I?
Think of CLAUDE.md as the persistent operating context for the repository.
It can explain things such as:
repository purpose
architecture
technology stack
important commands
coding conventions
project terminology
high-level constraints
This is knowledge Claude should frequently understand when working in the repository.
But there is a dangerous temptation here.
Once developers discover that Claude reads project instructions, they start putting everything into them.
Architecture.
Deployment procedures.
Testing instructions.
API documentation.
Feature requirements.
Historical decisions.
Troubleshooting information.
Business rules.
Eventually the permanent context becomes enormous.
That defeats one of the most important principles of context engineering:
Give the model the minimum sufficient context required to make the next good decision.
Permanent context should therefore remain relatively small.
Claude needs a map of the territory.
It does not need the contents of every building on the map.
Rules: How Do We Behave Here?
Some knowledge is not universal across the entire repository.
Perhaps API development follows one convention.
Testing follows another.
Database migrations have their own requirements.
Frontend code follows another set of practices.
Rules allow those instructions to become more modular and scoped.
Conceptually:
Project Context
|
+-- API Rules
|
+-- Testing Rules
|
+-- Security Rules
|
+-- Coding Conventions
This is already better than a monolithic instruction file because context can become more relevant to the work being performed.
But rules still answer primarily:
What should I know or obey while working here?
They don’t necessarily answer:
What exactly are we trying to accomplish today?
For that, we need another layer.
Intent: Where Are We Going?
This is the layer I believe is missing from many Claude Code architecture discussions.
Call it:
a Jira-derived intent
or some other execution contract.
The name matters far less than the responsibility.
An Intent describes the current desired outcome.
At minimum, a strong intent should establish:
Intent / Goal
What needs to become true?
Inputs / Context
What information is necessary to perform the work?
Outputs
What should exist when the work is finished?
Success Criteria
How will we know the result is correct?
For serious engineering work, it may additionally establish constraints, acceptance criteria, current-state assumptions, required evidence, validation expectations, and stop conditions.
This gives us a critical separation:
"What world am I operating in?"
↓
"What needs to become true?"
That is a much cleaner architecture than continuously expanding the project’s permanent instructions.
Skills: How Do We Do This Here?
Now suppose the intent says:
Create another outbound adapter using the organization’s established adapter architecture.
Claude should not have to rediscover the company’s adapter-development process every time.
That is organizational knowledge.
That is a Skill.
A skill can describe:
how the organization scaffolds an adapter
how APIs are implemented
how deployments work
how migrations are performed
how architecture reviews are conducted
how a particular type of feature is validated
The distinction becomes extremely useful:
Intent
WHAT needs to happen
Skill
HOW our organization normally does it
And skills have another major context-engineering advantage:
they can be loaded when needed rather than permanently occupying the working context.
That keeps the system lighter.
Agents: Who Should Solve This Part?
Not every task requires another agent.
This is where agentic systems frequently become unnecessarily complicated.
A subagent should exist because there is a concrete reason for delegation.
For example:
specialized expertise
context isolation
parallel independent investigation
security review
architecture analysis
repository exploration
An agent can receive a bounded assignment, work within its own context window, and return the relevant findings.
Conceptually:
Main Agent
|
+---- Architecture Agent
|
+---- Security Agent
|
+---- Repository Analysis Agent
But the important part isn’t merely creating agents.
It is deciding what crosses those boundaries.
Context Passing: The Hidden Architecture
Once multiple reasoning contexts exist, every boundary becomes an information contract.
The architecture should not automatically do this:
Main Context
|
| EVERYTHING
v
Subagent
|
| EVERYTHING
v
Main Context
That produces bloated context windows and noisy reasoning.
Instead:
Main Context
|
| minimum sufficient assignment
v
Subagent
|
| findings
| evidence
| relevant state
| source metadata
v
Main Context
That is context passing.
And context passing is one of the most important architectural responsibilities in a multi-agent system.
The question isn’t:
What information do we have?
It is:
What information does the next reasoning context require to perform its responsibility correctly?
That is a much more powerful question.
MCP and Tools: What Can the System Reach?
Eventually reasoning needs information or action outside the immediate context.
Maybe the agent needs to:
read Jira
inspect Confluence
query a database
interact with GitHub
examine an API
retrieve architecture documentation
perform an external action
That is the capability layer.
Tools give the agent capabilities.
MCP can provide governed interfaces to external systems and organizational resources.
This produces another clean distinction:
Skill
KNOWS how we do something
Agent
REASONS about something
Tool
DOES something externally
MCP
PROVIDES governed access to external capabilities/context
These responsibilities should not be casually mixed together.
Hooks: What Cannot Be Optional?
There is another class of requirement entirely.
Some things should not depend upon the model remembering instructions.
Suppose an organization requires:
secret scanning
schema validation
formatting
prohibited-file detection
required tests
security checks
validation of an Intent file
Writing:
“Claude, please remember to always do this.”
is weaker than deterministic enforcement.
That is where hooks become important.
A useful principle is:
If something absolutely cannot be bypassed, don’t leave it solely to probabilistic reasoning.
Use deterministic enforcement at the appropriate boundary.
Settings: What Is Actually Allowed?
Claude Code also needs a permissions and configuration boundary.
That is different again.
The system may know how to do something and even reason that it should do it, while still not being authorized to perform that action.
This gives us another architectural separation:
Intent → What must happen
Context → What must be known
Skill → How we do it here
Agent → Who reasons about a bounded problem
Tool → What external action can be performed
MCP → What external systems can be accessed
Hook → What cannot be optional
Settings → What the system is permitted to do
Now we are no longer discussing a folder structure.
We are discussing an agentic execution architecture.
Goal-Oriented by Default
There is one more principle that keeps this architecture from turning into an enormous workflow engine.
Don’t orchestrate everything.
If Claude has sufficient intent, context, capabilities, constraints, and success criteria to accomplish a task reliably, let it work toward the goal.
That is goal-oriented execution.
Add procedural orchestration only when the problem actually requires:
strict ordering
dependencies
approval gates
irreversible side effects
retries
recovery
coordinated parallel work
explicit failure handling
A useful architecture therefore looks less like a giant flowchart and more like this:
PROJECT CONTEXT
|
v
INTENT
What must become true?
|
v
MAIN REASONING
Goal-Oriented
|
+-------------+-------------+
| |
v v
SKILLS RULES
How we do this How we work here
| |
+-------------+-------------+
|
v
ORCHESTRATION
Only if needed
|
+----------+----------+
| | |
v v v
AGENT AGENT AGENT
| | |
+---- Context Contracts-+
|
v
TOOLS / MCP
External capability
|
v
HOOKS
Deterministic governance
|
v
VALIDATION
|
v
EVIDENCE
|
v
DONE
Notice what happened.
We didn’t create complexity for complexity’s sake.
We separated responsibilities.
Context Is the Fuel — Intent Is the Steering Wheel
There has been enormous attention recently around context engineering, and rightly so.
Context matters enormously.
But context by itself does not define purpose.
You can give an AI system perfect information and still leave it without a sufficiently precise definition of the outcome.
That is why I see two ideas converging:
Context engineering determines what the system needs to know.
Intent-driven engineering determines what the system needs to accomplish.
Put them together and the architecture becomes much stronger.
INTENT
What must happen?
|
v
CONTEXT
What must be known?
|
v
REASONING
What should we do?
|
v
CAPABILITY
What can we do?
|
v
GOVERNANCE
What must we obey?
|
v
VALIDATION
Did we accomplish it?
That is the loop.
Don’t Build an Agent Zoo
One of the easiest mistakes in this space is seeing all these capabilities and assuming every project needs all of them.
It doesn’t.
A repository does not become more agentic because it contains twelve agents, twenty skills, fifty hooks, and an enormous orchestration graph.
Complexity has a cost.
Every agent creates another context boundary.
Every workflow creates another failure path.
Every tool creates another capability surface.
Every integration creates another dependency.
Every additional context token competes for attention.
The architecture should therefore follow a simple rule:
Use the minimum sufficient architecture required to satisfy the intent safely and reliably.
Sometimes that means:
Intent → Claude → Tests → Done
Perfect.
Sometimes it means:
Intent
↓
Skill
↓
Claude
↓
Tool
↓
Validation
Also perfect.
And sometimes the consequences and complexity justify:
Intent
↓
Orchestrator
↓
Specialized Workers
↓
Tools / MCP
↓
Hooks
↓
Validation
↓
Evidence
Use that architecture when the problem requires it.
Not because the technology exists.
The Bigger Lesson
Claude Code becomes much more useful when a project gives it structure.
Absolutely.
But structure is only the beginning.
The larger opportunity is to create repositories that explicitly communicate:
Where am I?
Project context.
Where am I going?
Intent.
What do I need to know?
Context.
How do we do this here?
Skills.
What rules apply?
Rules.
Should someone else solve part of this?
Agents.
What information should cross that boundary?
Context contracts.
What external capabilities do I need?
Tools and MCP.
What cannot be optional?
Hooks.
What am I permitted to do?
Settings.
How do I prove I’m finished?
Validation and evidence.
Once those responsibilities become explicit, Claude Code stops looking like an AI assistant sitting inside a repository.
It starts looking like a governed engineering runtime built around intent.
And that, I believe, is where this entire generation of software development is heading.
The Principle
Give AI enough project structure to understand the world.
Give it enough context to understand the problem.
Give it explicit intent so it understands the destination.
Give it skills so it understands how your organization works.
Give it tools when it needs to act.
Give it agents only when delegation creates real value.
Govern what cannot be optional.
Orchestrate only what must be orchestrated.
And leave everything else goal-oriented.
That is how we keep agentic engineering powerful without turning it into another layer of enterprise complexity.
Comments