Code brokers boost developer productivity, but the other side of the coin accumulates silently: technical debt, security vulnerabilities, unmaintainable code. However, concrete methods exist to regain control.
This is the problem of the moment in generative AI: how to minimize the technical debt of the code generated every day by artificial intelligence? With the almost systematic use of code agents, companies face long-term code maintainability constraints. But good practices and technical solutions exist to maximize the maintainability of the code and get closer to, or even surpass, historical standards.
More code, faster, but not necessarily better
The observation is shared by the majority of companies: code agents (Claude Code, GitHub Copilot, Codex, Gemini CLI) make it possible to produce features at an unprecedented pace, but this acceleration has a downside. Without a rigorous methodological framework, the delivered code accumulates structural defects which become costly to correct. “The AI, if we do not guide it, will choose options which are not necessarily compatible with the architecture of the project”, summarizes Nicolas Gaudemet, chief AI officer of Onepoint. Security breaches, in particular, are not a subject to which the agent pays attention spontaneously if nothing forces him to do so. On the dependency side, the risk is twofold: the AI can rely on third-party libraries without checking their compatibility with the version used in the project, or conversely, redevelop bricks that already exist in the codebase, due to not knowing that they are available.
At SNCF Connect & Tech, the adoption of AI for coding was generalized at the start of 2024 in the form of auto-completion, then extended to agents in conversational mode during 2025. Vibe coding quickly generated mixed feedback among the company’s 800 tech employees. “We quickly realized that this way of working was not the most optimal,” explains Emmanuel Cordente, CTO of SNCF Connect & Tech. Describing his needs in the form of a cat was too imprecise, and above all insufficient. The result is a lot of code rework, strong variability from one generation to the next, and real time savings below expectations.
Give relevant and targeted context to your code agent
We already knew that the absence of relevant context is the main blocking point for agents who do not go into production in a company. In the case of code agents, context takes on an even more important character. The quality of the code generated by AI is directly proportional to the quality of the context provided to it. Naming conventions, implementation methods specific to the project, target architecture, version of the languages and frameworks used, existing components to be reused… So much information that the agent cannot guess if no one sends it to him. “It’s like a human: if we don’t tell him where things are, he won’t look for them in the right place,” summarizes Nicolas Gaudemet.
In practice, this context is structured in dedicated files, mainly agent.md files (read by the agent at the start of each task) and skills specialized by domain, for example a separate set of rules for the front-end and for the back-end. At Suadeo, a data and AI platform publisher, this approach is industrialized: development rules, naming conventions, structure of business objects, everything is described and transmitted to the agent. “We work with AI as we work with developers. We have naming rules, skills which explain how to code each method,” explains Mohamed Bendjebbour, R&D manager of the company.
The point, however, is not to pile up documentation. The LLM context window remains limited, and overloading it degrades the agent’s performance. Emmanuel Cordente insists on this trade-off: we must not re-explain what the model already knows, but focus the context on what is specific to the project and the organization. At SNCF Connect & Tech, the choice was made to store this documentation directly in the git repository. The use of MCPs completes the system by allowing the agent to access up-to-date documentation of libraries and languages, a critical point when we know that the models are often trained on previous versions. The other trap to avoid: letting the documentation take away from the code over the iterations. If the agent is not explicitly asked to update the documentation after each modification, the lag sets in and the context gradually loses its value.
Work in spec driven mode
Providing context is necessary, but not enough if the developer’s request itself remains unclear. This is the observation that pushed SNCF Connect & Tech to structure its agentic approach in Spec Driven Development mode. The goal? Specify precisely what is expected before letting the agent code. After an experimental phase carried out in 2025 with agents developed internally, the company now relies on open source frameworks such as SpecKit and BMAD to industrialize the approach. The first allows the development to be structured in four phases (specification, plan, division into tasks, implementation). The second goes even further by simulating a complete agile team with agents specialized by role (Product Manager, Architect, Scrum Master, etc.). “The objective is to correct the main problem we had with vibe coding, which is randomness. We want to describe it to have very low variability in the production of AI”, summarizes the CTO of SNCF Connect & Tech
But without going so far as to adopt a complete spec driven framework, the essential rule is to always plan before any major modification or addition of functionality. You must ask the agent to propose a plan and then challenge it (or use the plan mode, when it exists). “We must not let him rush headlong into a solution, but first ask him what the possible options are and propose a plan,” insists Nicolas Gaudemet. On the agent side, AWS Kiro natively integrates this spec driven logic: the tool transforms a prompt into structured specifications, then into technical design and implementation tasks, before generating any code.
Reliable, multi-level code reviews
Even with a rich context and well-constructed specifications, the code review remains the obligatory step before any release into production. “No line of AI-generated code should go into production without human validation, otherwise it’s a blank check,” says Mohamed Bendjebbour. The volume of code generated by the agents mechanically creates pressure on this step. “AWS had to reintroduce systematic human code reviews after noting that the pace of delivery was generating security vulnerabilities in production,” recalls Nicolas Gaudemet.
However, this bottleneck is reduced considerably when the upstream steps are well executed. Code produced with the right conventions, planned and divided into unit tasks, is reviewed much more quickly than a monolithic block generated in vibe coding. The other lever is to use the AI itself to pre-filter. For example, it is possible to have the code reviewed by a separate agent, in a separate conversation, to avoid bias from the first agent. Cross-referencing several AI models is also a good practice, before human validation. The principle is always the same: several levels of automated control, then a human who decides on sensitive files and architecture.
Maintainable code, well specified and compliant with project conventions, can be reviewed more quickly, debugged more quickly, and generates fewer downstream reworks. The time invested in upstream framing (context, specifications, rules) is largely recovered by reducing code rework downstream. Thus, beyond reducing technical debt, maintainable code paradoxically allows you to ship faster.
