Your AI Coding Tool Has No Idea What Your Codebase Is Supposed To Do

Manas Khare — Tue, 12 May 2026 04:12:55 +0000

Introducing Intent Files - the missing bridge between your repository and your AI

Every developer I know has hit the same wall.

You open Copilot or Gemini, ask it to write a service class, and it generates something that works — but violates half your team's coding standards. Wrong naming conventions. Logic too complex. The entire business flow crammed into one function. So you write another prompt to fix it. Then another. Every session. Every file. Every developer on the team independently re-explaining the same rules to the same tool that forgot everything the moment you closed the tab.

And it is not just standards. The prompt you spent twenty minutes crafting — the one that finally got the AI to understand your schema, your edge cases, your team's approach — is gone the moment the chat closes. Next week, when you or a new teammate needs to understand that code, there is nothing to go back to. No record of why it was structured that way. Just code. And code does not explain itself.

So you read it. You trace every reference. What calls this function. What this function calls. Under what conditions. You reverse-engineer intent from implementation — slowly, painstakingly, getting exponentially harder as the codebase grows.

Then there is the PR review. Before raising one you mentally run through a checklist hoping you covered everything. The lead engineer takes your code, pastes it alongside the team's standard guidelines into an AI prompt, checks it, comes back with comments. You fix. Resubmit. Repeat. Too much back and forth for something that should be automatic.

The longer you work with AI on a large project the worse it gets. By the time you are covering ten components in one conversation, the AI is mixing context from component two into component six's logic. It hallucinates solutions based on earlier discussion that had nothing to do with the current module. The fix everyone knows but nobody says out loud — start a new chat. Lose all the context. Begin again.

And if your team is doing this properly, someone has asked you to log your prompts into an Excel file. A reusable prompt library. A reasonable goal in theory. In practice you are trying to remember, after the fact, from a cluttered chat history, what you actually typed three hours ago. The AI automated your work and you got assigned manual work to document the automation. The prompts that produced the code are gone. The Excel file gets filled with approximations nobody will reuse.

Every session you also paste the same structural files. model.py in Django. Entity classes in Spring Boot. Object definitions in Salesforce. The schema the AI needs to understand your data layer — field types, constraints, relationships, enums. Every developer on the team independently re-explaining the same structure in every new session because the AI has no persistent awareness of your project.

Seven frustrations. One root cause.

AI has no permanent, structured, scoped awareness of your project. It knows everything from your chat and nothing from your codebase.

Your AI coding tool and your repository are two entirely disconnected systems. You are the only bridge between them. And you rebuild that bridge manually, from scratch, every single session.

The pattern that keeps repeating
Software engineering has always evolved by adding abstraction layers. Each layer hides the complexity below it and lets the engineer work at a higher level.

Machine code     ← what the CPU executes
Assembly         ← human-readable instructions  
C / C++          ← structured systems programming
Java / Python    ← managed high-level languages
Frameworks       ← domain-specific abstractions
???              ← what the engineer actually means

At every transition the lower layer became a build artefact — something generated, not hand-crafted. Nobody writes bytecode by hand. Nobody writes raw memory addresses. The generated output is trusted, verified by tooling, and largely invisible to daily work.

Each transition also shifted what it meant to be a skilled engineer. The valuable skill moved up the stack — from bit manipulation to memory management to algorithm design to system architecture. The engineer's job became progressively more about expressing intent clearly and less about managing implementation detail.

We are at the next transition. Code is becoming the build artefact. Intent is becoming the source.

Introducing Intent-Oriented Architecture
Intent-Oriented Architecture — IOA — is a methodology where human intent at each organisational level is explicitly declared, version-controlled, and treated as the source of truth for all downstream artefacts. Code, documentation, API specifications — all derived from intent.
It is built on four levels, each owned by a different role, each answering a different question.
Level 1 — project.intent
Written by the architect. Org-wide rules that hold everywhere — security mandates, architectural patterns, compliance requirements. Language independent. Platform independent. Written once, rarely changed. References your existing PMD rules, checkstyle config, and SonarQube settings. The AI is never asked to guess your standards — they are part of every compilation by default.
Level 2 — module.intent
The business contract. Pure intent — no language, no framework, no implementation detail. A Business Analyst can write this without knowing Java or Swift. Behaviours, business rules, edge cases, user journeys. The same file drives Android, iOS, backend, and web simultaneously.
Level 3 — language.intent
The lead engineer's institutional knowledge made explicit. MVVM enforced. Repository pattern for all data access. Coroutines for async operations. Dependency injection via Hilt. Every component in that language inherits this automatically — no hoping developers read the wiki.
Level 4 — component.intent
Developer owned. Inherits from the business module and the language guidelines. Adds platform-specific implementation detail and overrides where the platform genuinely requires different handling.

Each level answers a different question:

project.intent    ← What are our non-negotiables as an org?
module.intent     ← What does this feature do for the business?
language.intent   ← How do we write code in this language here?
component.intent  ← How does this specific component work?

And critically — no role is asked to do something outside their domain. The architect defines what goes into project.intent. The BA's requirements are the input for module.intent. Neither is asked to maintain a file format. The developer structures and maintains the intent. The source provides the knowledge. The developer ensures it is correctly captured.

What this looks like in practice
A component.intent file for an Android UserService looks like this:

id: USR-001-AND
type: component
extends:
  business: USR-001
  language: android-guidelines

implementation:
  - Expose authentication state as StateFlow for UI observation
  - Use UserRepository for all data operations via Hilt injection
  - Handle token refresh transparently via OkHttp interceptor

platform-specific:
  - Support biometric authentication as fallback login method
  - Cache session in EncryptedSharedPreferences only

overrides:
  - USR-001-B1: |
      Show biometric re-authentication prompt before
      allowing admin to manually unlock an account.
      Standard 5-attempt lockout otherwise unchanged.

Forty lines. A reviewer understands exactly what this component does, how it differs from the business default, and why — without reading a single line of Java.
The module.intent it inherits from was written by a BA in plain language. The language.intent it inherits from was written once by the lead engineer and applies to every Android component automatically. The project.intent security rules apply without being mentioned — they are always in scope.

What this unlocks
Framework migration becomes recompilation. Your .intent files never knew they were Java Spring Boot 2.7. They declared intent. Point them at Java 21 and Spring Boot 3.2 and generate fresh, idiomatic, technically-clean code. The accumulated technical debt does not migrate because it was never in the intent file.

Cross-platform consistency is guaranteed by design. Change business logic in module.intent once. Android is flagged stale. iOS is flagged stale. Each recompiles when the team is ready — independently, at their own pace, tracked by the tool. No risk of platforms silently diverging.
Business requirements become machine-executable. For the first time, what the BA writes directly drives what the code does. No translation layer. No "what did they actually mean." The intent file is the requirement.
Code reviews shift from archaeology to verification. Before raising a PR the developer runs aic status — all in sync — and aic audit — no violations. The lead reads forty lines of intent to understand what changed and why — then reviews the actual code focused entirely on subtle logic and edge cases, not procedural checklist items the tool already verified

Documentation is always in sync. Because it compiles from the same source as the code. Always current by definition.

AIC — the reference implementation
AIC is a lightweight CLI tool that compiles .intent files to any target language and version.

aic compile UserService --target java@21
aic compile UserService --target swift@5.9
aic compile UserService --target flutter

Same intent file. Multiple targets. One source of truth.
Three things AIC is not:
It is not a real-time compiler. It does not watch files and regenerate code continuously. It is invoked explicitly when intent changes. Generated code is committed to version control just like hand-written code.
It is not full regeneration. When intent changes, AIC reads the existing generated file, identifies exactly what changed in the delta, and surgically updates only the affected code. The git diff is clean and minimal. The rest of the file is untouched.
It is not its own AI. AIC uses whatever AI you already have configured — Claude, Gemini, Copilot, or a local Ollama model. No new subscriptions. No new API keys. No new trust decisions. You bring the engine. AIC brings the architecture.

You do not need the tool to start
IOA is a methodology first. A team can adopt it today with nothing but a folder and a text editor.
Create a /intent folder. Write a project.intent with your architectural rules. Write a module.intent before every feature. Write a language.intent capturing your team's conventions. Use these files as the primary reference in every code review.
That alone — without any tool, without any AI integration — eliminates most of the communication failures that plague software teams. Misunderstood requirements, undocumented architectural decisions, inconsistent patterns, knowledge locked in one person's head.
The tool makes IOA effortless. The methodology makes software teams coherent. Both have independent value.

The honest open questions
AI is not fully there yet. Generated code will have bugs. Complex platform-specific behaviour will sometimes require human correction. Edge cases declared in intent will sometimes translate imperfectly.
This is not a reason to wait. It is a reason to be honest.
The architecture is AI-model agnostic by design. As models improve the same .intent files produce better output automatically. No migration. No catch-up. The foundation remains. The engine gets stronger.
And this is the property that matters most — your .intent files do not age. They do not accumulate technical debt. They do not break when a framework updates. The worst case scenario is that your intent files sit unchanged for two years and compile dramatically better code when you come back to them. That has never been true of any other investment in a technology stack.
The open question that matters for the future is different. Today AI is an assistant you prompt session by session. The future is autonomous agents that maintain and evolve a codebase given a high-level instruction — the way a senior developer is briefed on a task and trusted to execute it. For that future to work, the agent needs a navigable structure. Training on thousands of lines of changing code is computationally infeasible and produces hallucinations as old patterns conflict with new ones. The answer is not better training. It is structured intent files — a map the agent navigates from project level to component level, arriving at precisely the right context for precisely the right task. IOA is not just a better way to work with AI today. It is the architectural foundation that makes autonomous AI development possible tomorrow.

The one thing
AI will never optimally maintain your codebase if it has to reverse-engineer understanding from code every single session.
If you plan to let AI handle significant parts of your development workflow — and that future is closer than most teams are ready for — then AI needs intent written in clear, structured, permanent language. Not inferred from syntax. Not rebuilt from chat history. Not pasted manually every session.

It needs to know how each component was intended to work. And it needs to maintain that understanding consistently — across sessions, across developers, across languages, across years.

Right now your codebase and your AI are two disconnected systems. You bridge them manually every day — pasting schemas, re-explaining standards, starting new chats when the old ones get too cluttered. That bridge is made of impulsive prompts and partial context. It breaks constantly and gets rebuilt constantly.

.intent files make that bridge permanent.

Not a workaround. Not a prompt library in an Excel file. A first-class architectural layer that integrates your project and your AI into a single coherent entity — where the AI knows your system the way a senior developer knows it. Deeply, structurally, permanently.
The question is not whether this integration needs to happen. It does. The question is whether you build the bridge deliberately — or keep patching it with duct tape one prompt at a time.

The full design document — covering IOA methodology, AIC implementation, file structure, inheritance model, commands, use cases, and proposed proof-of-concept experiments — is available at GitHub link.

If you run any of the proposed experiments, share your results. Positive results strengthen the methodology. Negative results improve it.

Originally published on Medium

DEV Community: Manas Khare

Your AI Coding Tool Has No Idea What Your Codebase Is Supposed To Do