Instructions Explain, Scripts Execute, Tests Prove
Coding agents can read a lot of code.
That usually isn't the hard part.
The harder part is everything an experienced engineer already knows but the repository doesn't clearly say. Organizing a project for coding agents is really about putting that knowledge in the right place.
A simple principle helps:
Instructions explain. Skills guide. Scripts execute. Tests prove.
🏗️ An Application Is Often Many Repositories
A modern application is rarely one repository.
It may be split across several:
app → application code and build pipeline
database → schema, migrations, seed data
app-infra → cloud resources, IAM, DNS, search
cluster-infra → Kubernetes clusters and shared services
deploy-manifests → environment-specific deployment configuration
An agent looking at only one repository cannot infer that entire relationship.
That is the first thing we should make explicit:
What repositories make up the application, and what does each one own?
That gives the agent a map before it starts navigating.
🧠 Instructions Explain What the Code Cannot
Instruction files such as AGENTS.md or CLAUDE.md should contain information the agent cannot reliably discover from source code alone.
For example:
Repository relationships
Architecture boundaries
How environments are organized
How tests should be run
Important operational constraints
Critical guardrails
The goal is not to document the entire repository.
The agent can already read the repository.
A good rule is:
If the agent can reliably discover something from the code, don't repeat it in the instructions.
Keep instructions short and focused.
Long instruction files consume context and make the important rules harder to notice.
🧩 Skills Guide Repeatable Procedures
Some engineering tasks follow the same process again and again.
For example:
Check deployment status
Investigate an incident
Compare environments
Validate a release
Inspect a scheduled job
Instead of expecting the agent to rediscover the procedure every time, package it as a skill.
Conceptually:
User Question
↓
Relevant Skill
↓
Known Procedure
↓
Tools / Scripts
↓
Result
A skill should tell the agent:
When to use it
What procedure to follow
Which tools or scripts to run
How to interpret the result
The advantage is that specialized instructions only need to load when they are relevant.
The main agent instructions stay small.
⚙️ Scripts Execute Deterministic Work
Suppose the procedure is:
Get deployments
Check pods
Check scheduled jobs
Compare versions
Identify failures
An agent could construct those commands every time.
But why make it reason through something deterministic?
Instead:
Agent
↓
Run Script
↓
Collect State
↓
Structured Result
↓
Agent Interprets Result
The script handles the repeatable mechanics.
The agent handles judgment.
This distinction is important:
Every step the agent doesn't have to reason through is one less step it can get wrong.
Use the model where reasoning adds value.
Use scripts where consistency matters more.
🛡️ Move Critical Guardrails Below the Prompt
Instructions are useful, but they are still guidance.
Consider a rule like:
Production cluster access is read-only.
You can put that in AGENTS.md.
But if the rule must always hold, don't rely on the model remembering it.
Move the constraint into deterministic controls:
Instruction
↓
Hook
↓
Permissions
For example:
The instruction says access is read-only
A hook blocks unsafe commands
Cluster permissions prevent writes entirely
The deeper the control is enforced, the less the agent has to remember.
An instruction is a request. A policy or permission is a guarantee.
✅ Tests Prove the Work
A coding agent shouldn't stop because a change looks correct.
It should have a way to verify the result.
Without validation:
Change Code
↓
Looks Correct
↓
Stop
With validation:
Change Code
↓
Run Test
↓
Failure?
↓
Fix
↓
Run Again
Tests give the agent evidence.
That changes the role of the human.
Instead of being the verification loop, the human becomes the reviewer of a result that has already been checked.
The same idea applies to agent tooling itself.
Skills, scripts, hooks, and configuration should also be validated like production code.
🔄 Let Skills Improve Through Use
Skills shouldn't be treated as finished artifacts.
The most useful improvements often come from real usage.
You may discover that:
The output is too verbose
A status is ambiguous
One workflow takes too long
A special case needs a shortcut
An important field is missing
Capture those learnings.
Then update the skill or script.
Use
↓
Observe
↓
Learn
↓
Improve
↓
Next Run Gets Better
Over time, operational knowledge moves out of people's heads and into reusable automation.
📚 Documentation Is Still for Humans
Agents need instructions, skills, scripts, and tests.
Humans still need architecture documentation.
A short README or architecture document should explain:
What the major components are
How they connect
Where they run
Which repositories own which responsibilities
The agent can be pointed to that documentation when needed.
There is no reason to copy all of it into the permanent instruction context.
🧭 Where Things Belong
A simple mental model:
| Need | Put It Here |
|---|---|
| How do repositories relate? | Instructions |
| What should the agent know? | Instructions |
| What repeatable process should it follow? | Skill |
| What can execute deterministically? | Script / Tool |
| What must always be enforced? | Hook / Permission |
| How do we know it worked? | Test |
| How does the procedure improve? | Learnings |
| What helps humans understand the system? | Documentation |
| What is the implementation truth? | Source code |
The general direction should be:
Move work toward the most deterministic layer possible.
If guidance can become a script, make it a script.
If a rule can become a permission, enforce it.
If an outcome can be tested, test it.
🎯 Final Thought
Making coding agents more effective isn't only about better models or larger context windows.
It's also about designing the engineering environment so the agent has less to infer, less to remember, and less to invent.
A well-organized project gives the agent:
A map of the repositories
Clear instructions
Reusable skills
Deterministic scripts
Enforced guardrails
Tests that prove the result
Instructions explain. Skills guide. Scripts execute. Tests prove.
The goal isn't to make the agent remember everything.
It's to organize the project so it knows where to look, what to run, what it is allowed to do, and how to prove the work is complete.
No comments:
Post a Comment