{"slug": "the-hard-part-of-ai-coding-agents-isn-t-writing-code-it-s-preserving-engineering", "title": "The Hard Part of AI Coding Agents Isn't Writing Code — It's Preserving Engineering Context", "summary": "A developer experimenting with AI coding agents on long-lived projects found that while agents can read a codebase and make changes, the engineering reasoning behind those changes — why a validation rule exists, whether a behavior came from an approved requirement or an agent's assumption — is routinely lost between sessions. The developer proposes giving different kinds of engineering knowledge distinct authoritative homes and inserting explicit human approval between specification and implementation, so agents surface knowledge gaps rather than silently converting reasonable inferences into code.", "body_md": "AI coding agents have become surprisingly good at reading a codebase and making changes across it.\n\nBut after using them on longer-lived projects, I started noticing a different problem.\n\n**The code survived between sessions. The engineering reasoning often didn't.**\n\nA new agent could see that a validation rule existed, but not necessarily why it existed.\n\nIt 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.\n\nAnd the longer I worked with coding agents, the more important this distinction became.\n\nAt first, I thought this was mostly a context problem.\n\nMaybe I needed better prompts.\n\nMaybe I needed a larger project instruction file.\n\nMaybe I needed to give the agent more documentation at the beginning of every session.\n\nThose things helped, but I eventually realized I was mixing several different kinds of knowledge together.\n\nA software project doesn't just contain code.\n\nIt also contains things like:\n\nPutting all of this into one large instruction file didn't feel like a real solution.\n\nThe problem wasn't just giving the agent more context.\n\n**The problem was giving engineering knowledge a structure.**\n\nImagine an agent finds this behavior in a codebase:\n\n**A user can retry an operation 5 times within 60 minutes.**\n\nThe code can tell the agent that this rule currently exists.\n\nBut it doesn't necessarily tell the agent:\n\nAn agent can infer some of this.\n\nAnd that's exactly where things can become dangerous.\n\nA reasonable inference is still an inference.\n\nFor some engineering decisions, I don't want the agent to make the most reasonable guess.\n\nI want it to say:\n\n**I don't have enough authoritative information to make this decision.**\n\nThis became one of the principles I cared about most.\n\nIf an agent needs a product decision that doesn't exist yet, I don't want the process to become:\n\n**Agent makes a reasonable assumption → Agent implements it → Assumption becomes code → Code eventually looks like the original requirement**\n\nInstead, I wanted something closer to:\n\n**Missing authoritative knowledge → Knowledge Gap → Human decision → Authoritative knowledge → Implementation**\n\nThe important difference is that the human isn't reviewing an assumption after it has already become part of the implementation.\n\nThe decision happens before the implementation depends on it.\n\nThat led me to a broader idea:\n\n**Different kinds of engineering knowledge should have different authoritative homes.**\n\nA feature's behavior shouldn't be hidden inside an architectural document.\n\nAn architectural constraint shouldn't quietly live inside a prompt.\n\nA product decision shouldn't exist only in a chat transcript.\n\nAnd a verification result shouldn't redefine the requirement it was supposed to verify.\n\nThe structure I ended up experimenting with separates things like:\n\nThe exact structure matters less than the principle behind it:\n\n**There should be a clear answer to \"where does this knowledge belong?\"**\n\nAnother problem appears once agents can do more than generate isolated snippets.\n\nIf an agent can inspect the project, modify multiple files, run tests, and continue through a workflow, then \"human in the loop\" can easily become:\n\nThe agent did everything and the human looked at it afterward.\n\nThat's useful, but it's not the same as authorization.\n\nFor certain transitions, I wanted the human decision to be explicit.\n\nFor example:\n\n**Human Intent → Specification → Human Approval → Implementation → Verification / Review**\n\nThe agent can help discover and define the Specification.\n\nBut approving what the system is supposed to do is a different responsibility from implementing it.\n\nThat boundary turned out to be important.\n\nI found a similar boundary around verification and review.\n\nSuppose verification discovers a problem.\n\nIt is tempting to let the same process immediately fix it and continue.\n\nBut then verification is no longer only answering:\n\nDoes the implementation satisfy the expected behavior?\n\nIt is also changing the thing it's evaluating.\n\nI prefer findings to go back through the appropriate engineering workflow and then be evaluated again against the new state.\n\nThat keeps verification about evidence rather than self-correction.\n\nEventually I turned these ideas into an open-source project called **Gnomon**.\n\nGnomon 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.\n\nIt doesn't replace Claude Code, Codex, or another coding agent.\n\nThose agents still inspect the repository, write code, run tests, and perform the actual engineering work.\n\nGnomon provides the system around that work.\n\nA simplified lifecycle looks like this:\n\n**Human Intent → Relevant Project Knowledge → Specification → Human Authorization → Agent Execution → Tests / Evidence → Verification / Review → Next Change**\n\nEverything is repository-local.\n\nThe 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.\n\nThe goal isn't to make the model smarter.\n\n**The goal is to give the model a better engineering environment to work within.**\n\nI've been using Gnomon itself while developing real projects, and that has been one of the most useful parts of the process.\n\nSome problems only became obvious when I actually had to live with the workflow.\n\nFor example, I found cases where the CLI itself was recommending commands that had been removed during an earlier redesign.\n\nThe underlying workflow was correct, but the guidance had become stale.\n\nFixing that led to another useful principle:\n\n**Recommendation code shouldn't become another source of engineering truth.**\n\nInstead of hardcoding assumptions such as:\n\n**Approved → Implementation**\n\nthe CLI now derives available actions from the same eligibility rules used by the rest of the system.\n\nIt's a small example, but it's exactly the kind of drift I'm trying to prevent at a larger scale.\n\nGnomon is still early.\n\nI don't think I've found the final answer to working with coding agents on long-lived software projects.\n\nThere 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.\n\nBut one thing I'm increasingly convinced of is that better code generation alone doesn't solve the engineering problem.\n\nAs agents become better at implementation, preserving the reasoning, decisions, constraints, and evidence around that implementation becomes more important.\n\nThat's the problem I'm exploring with Gnomon.\n\nThe project is open source:\n\n**GitHub:** [https://github.com/yasintqvi/gnomon](https://github.com/yasintqvi/gnomon)\n\nI'd especially like to hear from people using coding agents on real, longer-lived projects:\n\n**How are you preserving requirements and engineering decisions across agent sessions without turning your project instructions into one giant context file?**", "url": "https://wpnews.pro/news/the-hard-part-of-ai-coding-agents-isn-t-writing-code-it-s-preserving-engineering", "canonical_source": "https://dev.to/yasin_taghavi_5768e549edc/the-hard-part-of-ai-coding-agents-isnt-writing-code-its-preserving-engineering-context-5bhf", "published_at": "2026-09-25 09:57:58+00:00", "updated_at": "2026-09-25 10:00:40.099465+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "mlops"], "entities": [], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/the-hard-part-of-ai-coding-agents-isn-t-writing-code-it-s-preserving-engineering", "markdown": "https://wpnews.pro/news/the-hard-part-of-ai-coding-agents-isn-t-writing-code-it-s-preserving-engineering.md", "text": "https://wpnews.pro/news/the-hard-part-of-ai-coding-agents-isn-t-writing-code-it-s-preserving-engineering.txt", "jsonld": "https://wpnews.pro/news/the-hard-part-of-ai-coding-agents-isn-t-writing-code-it-s-preserving-engineering.jsonld"}}