Waterfall learning is dead

Waterfall learning is my name for putting a project on hold until you've learned the subject. The name borrows from waterfall development: finish the preparation, then start the work.

For an engineer who owns a codebase an agent is building, that order is dead. An agent can suggest an unfamiliar pattern and implement it in the same session. You can begin with a product you want to build and discover the subjects you need to learn as you go. Trying to prepare for every one of them before starting would mean studying for decisions you might never face.

Learning while writing code has always been part of engineering. The agent changes how far the implementation can move while your knowledge stands still. You can finish several features and accumulate decisions you'd struggle to explain, even though you're the person responsible for what happens next.

A few weeks later, you may want to change one of those features. The agent can inspect the code, but a fresh session won't contain a product constraint you never wrote down or the reason you rejected an alternative. You'll need to recover that context and decide whether the earlier choice still makes sense.

Keeping a record helps. An architecture decision record captures a decision along with its context and consequences, so someone returning to the project can understand the reasoning behind it.¹ You still need enough knowledge of the subject to judge whether that reasoning holds for the change you're proposing.

You can ask the agent to explain. It may give you a detailed plan, compare alternatives, and account for the questions you raise. But the explanation can assume background you don't have. You ask about an unfamiliar term, and the answer introduces another idea you need to understand before you can follow the first one.

After a few rounds, it's tempting to approve the plan and promise yourself you'll test the result. Testing can tell you whether the feature behaves as expected. It leaves other questions open, such as whether you've accepted more maintenance work than the feature warrants. People using AI at work report both lack of time and missing domain knowledge as barriers to checking its output.² More explanation doesn't necessarily solve either problem.

I think you have to separate the understanding needed for the current decision from the deeper study it prompts. Before approving a change, you need to understand why the proposed approach fits your product and what you're accepting by choosing it. If an unanswered question could change that decision, it needs attention during the session. Leaving it for later would mean agreeing to something you haven't understood.

Once you can make that decision, you may still want to learn the wider subject. You might want to understand the alternatives in more depth or recognise other situations where the approach would be useful. Taking that on during the coding session can interrupt the try, fail, tweak rhythm that makes working with an agent useful. Give the deeper study its own time between tasks, while you still remember what made the subject worth learning.

Before the session ends, ask the agent to identify the general subject behind the discussion. A question about a version check might become a request to learn how optimistic concurrency works. A discussion about deployment probes might point you towards the differences between readiness, liveness and startup probes. Keep the project's decision in its records, and take the underlying subject with you to study.

Sophia is an app that builds private courses around what you want to learn. With your coding agent connected through MCP, you can ask it to send that subject to Sophia, along with relevant sources and what you already know. You can make the request while the agent still has the context of your questions, without having to reconstruct the discussion later.

Sophia plans the course and leaves it queued until you choose to generate the lessons. You can carry on with the coding session, then open the app when you have time to study. Read a few short lesson cards in a five-minute gap or work through more of the course in a longer sitting. The course gives you a sequence to follow through the subject, beyond the particular question that came up while building.

On the next task, you might recognise a pattern you've studied and see a reason to question it. You can ask the agent to compare it with an alternative, or point out a consequence the plan hasn't addressed. You learned the subject because one project called for it; you can use that understanding wherever the same problem comes up.

Sophia is coming to the App Store, iOS first. Join the waitlist for an email at launch.

Footnotes

1. Michael Nygard, “Documenting Architecture Decisions”, 15 November 2011. Describes records of architectural decisions, their context and consequences, and their use when revisiting earlier choices. ↩

2. Lee et al., “The Impact of Generative AI on Critical Thinking”, CHI 2025, section 4.3.2. A survey of 319 knowledge workers across professions; these barriers are self-reported, not measurements of code-review performance. ↩