AI coding agents have become surprisingly good at reading a codebase and making changes across it.
But after using them on longer-lived projects, I started noticing a different problem.
The code survived between sessions. The engineering reasoning often didn't.
A new agent could see that a validation rule existed, but not necessarily why it existed.
It could see an implementation, but not whether that behavior came from an approved requirement, an architectural decision, or simply an assumption made by another agent three sessions ago.
And the longer I worked with coding agents, the more important this distinction became.
At first, I thought this was mostly a context problem.
Maybe I needed better prompts.
Maybe I needed a larger project instruction file.
Maybe I needed to give the agent more documentation at the beginning of every session.
Those things helped, but I eventually realized I was mixing several different kinds of knowledge together.
A software project doesn't just contain code.
It also contains things like:
Putting all of this into one large instruction file didn't feel like a real solution.
The problem wasn't just giving the agent more context.
The problem was giving engineering knowledge a structure.
Imagine an agent finds this behavior in a codebase:
A user can retry an operation 5 times within 60 minutes.
The code can tell the agent that this rule currently exists.
But it doesn't necessarily tell the agent:
An agent can infer some of this.
And that's exactly where things can become dangerous.
A reasonable inference is still an inference.
For some engineering decisions, I don't want the agent to make the most reasonable guess. I want it to say:
I don't have enough authoritative information to make this decision.
This became one of the principles I cared about most.
If an agent needs a product decision that doesn't exist yet, I don't want the process to become: Agent makes a reasonable assumption → Agent implements it → Assumption becomes code → Code eventually looks like the original requirement
Instead, I wanted something closer to:
Missing authoritative knowledge → Knowledge Gap → Human decision → Authoritative knowledge → Implementation
The important difference is that the human isn't reviewing an assumption after it has already become part of the implementation.
The decision happens before the implementation depends on it.
That led me to a broader idea:
Different kinds of engineering knowledge should have different authoritative homes.
A feature's behavior shouldn't be hidden inside an architectural document.
An architectural constraint shouldn't quietly live inside a prompt.
A product decision shouldn't exist only in a chat transcript.
And a verification result shouldn't redefine the requirement it was supposed to verify.
The structure I ended up experimenting with separates things like:
The exact structure matters less than the principle behind it:
There should be a clear answer to "where does this knowledge belong?"
Another problem appears once agents can do more than generate isolated snippets.
If an agent can inspect the project, modify multiple files, run tests, and continue through a workflow, then "human in the loop" can easily become: The agent did everything and the human looked at it afterward.
That's useful, but it's not the same as authorization.
For certain transitions, I wanted the human decision to be explicit.
For example:
Human Intent → Specification → Human Approval → Implementation → Verification / Review
The agent can help discover and define the Specification.
But approving what the system is supposed to do is a different responsibility from implementing it.
That boundary turned out to be important.
I found a similar boundary around verification and review.
Suppose verification discovers a problem.
It is tempting to let the same process immediately fix it and continue.
But then verification is no longer only answering:
Does the implementation satisfy the expected behavior?
It is also changing the thing it's evaluating.
I prefer findings to go back through the appropriate engineering workflow and then be evaluated again against the new state.
That keeps verification about evidence rather than self-correction.
Eventually I turned these ideas into an open-source project called Gnomon.
Gnomon is a CLI and repository structure for building software with AI coding agents while keeping project knowledge, specifications, human decisions, execution, and verification explicitly separated.
It doesn't replace Claude Code, Codex, or another coding agent.
Those agents still inspect the repository, write code, run tests, and perform the actual engineering work.
Gnomon provides the system around that work.
A simplified lifecycle looks like this:
Human Intent → Relevant Project Knowledge → Specification → Human Authorization → Agent Execution → Tests / Evidence → Verification / Review → Next Change
Everything is repository-local.
The durable knowledge is primarily Markdown, with small structured artifacts where needed. There is no database, hosted service, or requirement to move the project into another platform.
The goal isn't to make the model smarter.
The goal is to give the model a better engineering environment to work within.
I've been using Gnomon itself while developing real projects, and that has been one of the most useful parts of the process.
Some problems only became obvious when I actually had to live with the workflow.
For example, I found cases where the CLI itself was recommending commands that had been removed during an earlier redesign. The underlying workflow was correct, but the guidance had become stale.
Fixing that led to another useful principle:
Recommendation code shouldn't become another source of engineering truth.
Instead of hardcoding assumptions such as:
Approved → Implementation
the CLI now derives available actions from the same eligibility rules used by the rest of the system.
It's a small example, but it's exactly the kind of drift I'm trying to prevent at a larger scale.
Gnomon is still early.
I don't think I've found the final answer to working with coding agents on long-lived software projects.
There are still interesting questions around how much structure is useful before it becomes bureaucracy, how human authorization should work in automated environments, and how much knowledge an agent should load for a particular task.
But one thing I'm increasingly convinced of is that better code generation alone doesn't solve the engineering problem.
As agents become better at implementation, preserving the reasoning, decisions, constraints, and evidence around that implementation becomes more important.
That's the problem I'm exploring with Gnomon.
The project is open source:
GitHub: https://github.com/yasintqvi/gnomon I'd especially like to hear from people using coding agents on real, longer-lived projects:
How are you preserving requirements and engineering decisions across agent sessions without turning your project instructions into one giant context file?