Essay · May 13, 2026

We learned the right methods. Then we learned to bypass them.

When you train as a developer, you learn very healthy things. User needs, domain expert interviews, specifications, functional analysis, data flows, data models, architecture, diagrams, state machines, use cases, test strategies. All of this training rests on a simple idea: a good software system shouldn’t come out of nowhere. It should be born from a clear understanding of reality.

Intellectually, all of this is correct. And yet, in real life, things don’t always work that way.

In many teams, you start with a few exchanges with the client, a few concrete examples, a list of needs. Specifications sometimes become a simple grocery list. Diagrams exist, but rarely exhaustively. Architecture decisions are made, but not always formalized. This isn’t necessarily negligence. It’s often a trade-off between time, pressure, velocity, and the trust placed in the experience of the developers on the team.

Over the years, you get very good at this implicit economy. You merge roles. You become a programmer-analyst, or an analyst-programmer, depending on which word you prefer. You develop instincts. You know where to draw a boundary. You know when to tighten an API. A huge portion of this skill stops being visible because it lives in your head. This invisibility was long compatible with excellent productivity.

The illusion of the sufficient prompt — then the glass ceiling

Then AI coding arrived in our IDEs, and a very exciting first phase began.

At first, the illusion was almost perfect. You asked for a method, a service, an endpoint, a component. The tool completed code, proposed tests, suggested refactorings. And it really worked. What was working at that moment wasn’t just the AI. It was mostly the fact that context stayed in the developer’s head. The architecture, the product history, the business constraints, the decisions made with a client six months earlier — none of that was in the prompt. It all lived in my head, and the AI operated within the space I was bounding myself at every moment.

A few months later, I started wanting to delegate more. Not just fragments of code, but larger, more consistent chunks. And that’s when the glass ceiling appeared. The AI quickly ran into what was nowhere: the reasons behind decisions, the implicit constraints, the architecture choices, the history of trade-offs. I had to reframe it, remind it of rules, correct assumptions. Worse, all of this was scrolling through chats. One conversation buries another. An important decision was made, but it dissolved into the stream of interactions.

From notes to plans: the beginning of context engineering

My first reaction was trivial but structural: I started having it take notes. Not for appearances. Not to satisfy some abstract documentation principle. Just to not lose the clarifications, the reasoning, and the decisions made along the way.

After a few months, this evolved toward more explicit plans. People started talking about context engineering. I preferred to stay light: make plans, keep them in the repository, close them properly, archive them. This lightweight approach worked well. But it also revealed a new requirement: making plans isn’t enough if those plans reinvent each time an analysis that should have existed in a more stable form.

2026: better models demand better specifications

The real turning point came at the beginning of 2026.

Models became more autonomous, more proactive, more capable of chaining work steps on their own. And a paradox emerged: the more powerful they became, the more they demanded better context. To get better code, it was no longer enough to prompt better. You had to analyze better, slice better, design better, document better.

I noticed something striking: recent models were themselves proposing to add specification steps. They were asking for more precision, more constraints, more structure. The AI industry itself seemed to be rediscovering what software development has known for decades: the quality of a system also depends on the quality of the artifacts that precede the code.

This forced me to look at a very personal bias. Like many experienced developers, I had gotten into the habit of leveraging my experience to compress analysis into my head. I could go directly from a need to a reasonable implementation because user stories, decision tables, functional flows, states, entity relationships, architecture — all of it already lived mentally in me. AI put this shortcut in crisis. Not because it’s incapable, but because it doesn’t benefit from that implicit memory as long as you don’t externalize it.

The real return to foundations

From that point, the conclusion became inescapable: spec-first isn’t a trend. It’s a return to foundations.

If I truly want to collaborate with AI, I have to start doing explicitly what I had ended up doing mentally. Define the product intention. Clarify the operational reality. Establish objectives. Set constraints. Choose the stack knowingly. Describe the architecture. Name the boundaries. Document functional flows. Explain design decisions. Plan the test strategy. None of this is new. What’s new is the incentive.

For decades, much documentation ended up being seen as wishful thinking. Something you should maintain, but that costs a lot, degrades quickly, and slows delivery if it becomes too heavy. With AI, this dynamic changes profoundly. Good documentation stops being just the team’s moral debt. It becomes a velocity multiplier. It becomes alive because it directly feeds a working partner that can read, compare, propose, challenge, write, test, and navigate between multiple layers of the system.

The AI journey evolved too: the birth of intellectual segregation

There’s something important that isn’t stated clearly enough: the AI journey itself has evolved. And this evolution is generating strong intellectual segregation within the profession.

On one side, there are those who have embraced the discipline of analysis. Sequence diagrams, finite state machines, decision tables, functional flows. These people have become analysts in the strong sense of the term, and AI has become their programmer. They deliver precise, structured, actionable specifications — and it produces coherent, tested, vision-aligned code. On the other side, there are those who continued in prompt-and-code mode, more or less sophisticated, but without raising their analysis discipline. The gap between the two groups is widening rapidly.

A software engineer, at bottom, does something simple: discovers a world, gets interested in it, defines a product, then mobilizes analysis, design, and architecture tools to give it form. What AI has changed is that the “giving form” part can now be largely delegated. What remains irreplaceably human is the “understand, define, structure, decide” part.

Shared discomfort: unease, humility, and false hopes

Many teams intuitively sense that a return to foundations is needed. They understand that analysis, design, and architecture must come back to the foreground. But this intuition is often accompanied by unease. People know something is missing, without knowing exactly how to put it back in place.

I’ve seen teams wondering what documentary form to adopt, what level of detail to target, how to avoid producing useless documents, and above all how not to make a methodological mistake. This fear of doing it wrong produces a paradoxical effect: instead of getting things moving again, it encourages standstill. You wait for a strong signal from peers, from major vendors, from consulting firms. That signal never arrives clearly. Meanwhile, teams spin in place thinking they’re being careful.

There’s also a more uncomfortable but essential dimension. For developers with ten, fifteen, or twenty years of experience, it’s hard to accept that they may not be as solid as they thought on certain fundamentals. I say this against myself too. In my own project, I created technical debt very quickly. The first draft was produced in a phase of pure vibe coding: mixed levels, services and DAO access in controllers, blurry separations. It was objectively ugly. That moment forced me to an unpleasant realization: I wasn’t properly applying the analysis and design that I thought I had mastered.

In this state of hesitation, another reflex often appears: the hope that a framework, a tool, or a trending mode will solve the problem for you. Yesterday it was Copilot mode. Today everyone talks about Claude Code. Tomorrow it will be something else. I don’t believe in that magic. Changing tools can improve some things, but none of it fixes the fundamental problem if the team hasn’t reconnected with its core role: analyst, designer, architect, tester, domain expert — not just code producer.

Not choosing a lightweight method means choosing standstill

The good news is that it’s not necessary to return to the methodological weight of the past.

The parallel with software architecture seems illuminating. For a few years, microservices were sold as a panacea. We saw the result: explosion of operational complexity, maintenance burden, and fragile interfaces. The market didn’t return to the monolith out of nostalgia. It returned to the modular monolith because it was looking for a better equilibrium point. We need to do exactly the same thing with AI methodology.

We also need to avoid the RUP reflex. Large methodologies that claim to cover everything — Rational Unified Process with its monster templates — collapsed under their own weight: too heavy, too rigid, too removed from project reality. What should exist instead is a project-specific methodology: lightweight, pragmatic, deliberately chosen. The most structuring choice is simple: decide that part of the method should live in the codebase itself, in simple, versioned, human-readable and AI-readable formats.

From the analyst who uses a method to the methodologist who designs it

This is where something fundamental was revealed to me.

I had an analyst-programmer approach. I cared about system architecture, I had good experience, I used AI in plan mode. I interacted with it to create analyses, concepts, decision tables. But I was missing a real methodology. What I was doing was good, but it was artisanal. Each plan, each artifact, each documentary form was reinvented along the way.

A friend showed me his way of working, which had consisted very early in his project of writing templates, a methodology for using them, and skills — in the modern AI sense: specialized instructions, defined-role agents, formalized analysis sequences. These templates, this methodological guide, and these skills form a system. The result: once this methodology was refined, everything became uniform, systematic, repeatable. The work accelerated. It became rigorous and reliable.

What struck me was the difference in level. There’s the analyst who USES a method. And there’s the methodologist who DESIGNS the method suited to the project. The methodologist takes as their primary object not the product, not an architecture or a concept, but the guides that orient those activities themselves. These meta-decisions form the framework within which the analyst, designer, and AI subsequently work.

This discovery launched me into a major retrofitting project: taking the material produced so far — at variable format, variable depth — and re-injecting it into a methodologized, uniform format. Templates, patterns, naming conventions, cycles, phases. There’s work to do, but it’s the right direction.

The major lesson I drew from all this, I visualized as three levels:

Before AI, the analyst-programmer operated at the bottom two levels. Now, AI occupies the bottom level with growing competence. What remains irreplaceably human is what happens at the upper two levels. The human must now be a visionary-methodologist capable of defining visions, designing appropriate methodologies, orchestrating analyses, laying out architectures — and AI produces the code. This isn’t a weakening of the developer role. It’s an elevation.

The tools that embody this approach: examples, not endpoints

The ecosystem hasn’t stopped at theory. Tools have started to materialize this methodological elevation concretely. Claude Code, which has established itself as one of the most popular environments of the moment, is a striking example. With extensions like Super Powers, it goes well beyond ordinary plan mode to offer a methodological structure directly integrated into the work experience: interactive workflows, standardized artifact organization, a way of guiding the agent that recalls interaction with an analysis partner more than a simple code generator.

But this is where you need to resist a familiar reflex: seeing in a popular solution the definitive solution. Claude Code and Super Powers are examples to study, starting points to adapt — not a norm to copy as-is. What makes this approach powerful isn’t tied to a particular tool. It rests on a principle: an AI agent is capable of interacting at a methodological level with anyone who is willing to organize their work at that level.

Methodological customization must be prudent. You don’t restructure your workflow with every new trend. But it delivers real benefits when done with discernment. A team developing a security platform doesn’t have the same analysis toolset as a team building a content management SaaS product. The methodology must reflect that reality.

The debt we refuse to face

In many organizations, what’s valued is moving the business forward. That’s normal up to a point. But this logic has a blind spot: reverse engineering, documentary reconstruction, and code hygiene almost never look good in a status report. When you’re catching up on months of technical negligence, you don’t give the impression of inventing a spectacular new feature. And yet, without this step, the benefits of AI don’t multiply properly.

In my case, I ended up doing a several-week moratorium to put the code back in order. Adding Javadoc. Cleaning up warnings. Introducing quality guardrails. Hardening conventions. It was after this restoration that the multiplicative benefits of AI started compounding more effectively.

In a brownfield, this catch-up may require significantly slowing new feature delivery in order to reconstitute the conditions that will make velocity sustainable. You have to accept that this work sometimes resembles a strategic retreat: stop, look at yourself honestly, name the debt, re-establish healthier foundations, then restart with different momentum.

Documents, templates, skills: a structure that lives in the repository

To get moving again, you have to commit to three families of artifacts directly in the repository.

The first family: work plans. Plans with a minimal structure, guardrails, a status, a history, and the ability to be reviewed, challenged, amended, then archived. These plans become an interaction space between analysts, designers, developers, and AI. If you want real collective velocity, you need to start versioning work plans instead of letting them dissolve in chats or meetings.

The second family: documents that describe the current truth of the system. Not in abstract prose. A structure parallel to the code, reflecting its organization and main boundaries. Architecture documents, feature docs, boundary and mapping documents. Functional flows, design decisions, interface contracts. When this structure exists, it becomes readable by a human without immediately diving back into the code, and exploitable by AI as generation and verification context.

The third family: templates and skills. Templates that give an expected form to analysis and decision-making artifacts. AI skills that implement specific patterns: a skill to produce a feature analysis, a skill to model a state machine, a skill to conduct an architecture review. These templates and skills form the living core of the methodology. They make work systematic and repeatable, not just documented.

There’s also an underrated accelerator in this setup: dictation. To produce quality context, you need to be able to communicate massively — verbalize nuances, reasons, constraints, trade-offs. In 2026, I no longer believe you can sustain that volume of elaboration at the keyboard alone. Fluid speech frees richer, less self-censored thinking that’s faster to deposit. You stop economizing on words. Then AI helps sort, condense, reformulate.

Greenfield or brownfield, the logic is the same

In a greenfield project, all of this is relatively simple. You can put the documentary structure, templates, and skills in place from the start and grow them in parallel with the code.

In a brownfield, it’s harder. You need a reverse-engineering phase. You need to choose the most critical modules, bring into the documents the essential boundaries, mappings, interactions, and implicit decisions. It’s a progressive transfer of information that still lives in developers’ heads toward a more stable documentary structure. But this transfer doesn’t work well if the team refuses to face its debt. Getting back in motion starts precisely with choosing a structure simple enough to be adopted and useful enough to become alive.

AI at every level — down to engineering behavior

AI isn’t just a code generation tool. It becomes useful at every floor. It can participate in product brainstorming. It can challenge a positioning. It can help refine an architecture. It can reformulate requirements. It can point out fuzzy areas in a workflow. It can propose a reasonable test strategy. It can then do very concrete pair programming on the code itself.

What struck me most recently was a subtle but decisive shift. With the same scripts, the same documents, the same conventions, a more recent model started taking initiatives I hadn’t explicitly requested. To validate an evolution touching both the interface and the database, the agent noted that it had scripts, test landmarks, Admin UI access, and a demo environment already documented in the repository. It understood it had to open a browser, log in, use the Demo Device provided by the bootstrap, generate the right data, and verify the end-to-end scenario.

AI autonomy doesn’t come only from its internal advances. It also comes from the quality of the documentary and operational world you insert it into.

The developer is no longer the keeper of everything

For a long time, the implicit figure of the heroic developer dominated: the one who understands everything, remembers everything, carries the architecture, business logic, historical debt, exceptions, and unwritten rules in their own head. This figure hasn’t disappeared, but it’s losing its central advantage. What becomes strategic is no longer holding information in yourself. It’s knowing how to structure it, write it, articulate it, make it exploitable by other humans and by AI.

The developer this period favors is the one who knows how to understand the product, understand the client, understand the constraints, understand the architecture, make design choices, document those choices, and then put AI to work within that framework. Not just to code faster. To design more accurately, test more intelligently, and maintain a more explicable system.

And that often requires a more demanding gesture than we readily admit: accepting to move toward more abstract levels of thinking, acknowledging that we’ve let certain parts of our craft rust, and deliberately restoring rigor where habit and speed had ended up compressing everything into our heads.

Conclusion

French: Version française de cet article

See also: From code to intent

See also: AI coding manifesto