翻訳待ち：How to write production-quality code with AI

AI サービスが一時的に利用できないため、復旧後に翻訳を補完します。

A note from the author What this document is — and what it is not PAAD is a set of skills for AI coding assistants, built on one idea: engineering-driven AI, not AI-driven engineering. The engineer makes the decisions, and sees each one while there is still time to change it. Technical debt is where the difference appears: PAAD's review gates make specification-driven development more rigorous, so debt accumulates more slowly, and agentic-architecture later gives an experienced developer a way to manage the debt that does accumulate — a step AI-led engineering does not include. Everything you need to run PAAD is in this course: what each skill does, why it is designed the way it is, and the evidence behind it. It is also a document, and a document is one particular kind of teaching tool. This first section describes what this document does well, and why it cannot replace training with an instructor. What a document does well, this one tries to do in full. It is a reference: searchable, quotable, re-readable the night before you introduce the loop to your team. It works at your pace and in your timezone, it costs nothing to distribute, and it is stable — you can link to it in a design discussion or a decision record. Some things, though, no document can do, however carefully written. They are properties of the medium, not gaps in the material. PAAD is something you practise, not a set of facts to learn. Reading that you should argue with an agent's plan is a different skill from doing it in a live session, with someone there to correct you halfway through. The examples here are necessarily generic or drawn from my own work, while the cases that decide whether any of this is worth adopting live in your codebase, under your constraints. When an agent behaves strangely — and it will — working through the strangeness together in real time is high-value and unrepeatable in prose. And a document cannot answer "but what about our situation," nor check whether it has been understood: "I read it, and I understand it" is invisible from the inside, which is a large part of why instructors exist. Two further limits are organisational rather than individual. A methodology is a team property — five people reading separately produce five private interpretations, where a team working through the material together produces one agreed norm. And when adoption stalls, it usually stalls for organisational reasons: mismatched expectations, unclear ownership, a senior engineer who is not yet convinced. Those are legitimate obstacles, they are invisible to a document, and they can be addressed in a live discussion. And a document goes out of date: the tools named in these modules change monthly. This page is accurate as of the day it was written; a conversation is accurate today. The optional appendix “Teaching this to your team” covers this in more detail: what a team still has to do once the material is understood, and who has to own each piece of it. One consequence of all this is worth acting on. A document cannot hear you — so if a module confused you, a skill did not behave as described, or you got stuck somewhere between reading this and running it, telling me is the most useful thing a reader can do, and it is how this course improves. Live training exists for the pieces named above that a document cannot provide — practice on your own code, questions about your situation, one shared norm instead of several private readings — and arranging that, or sending that feedback, both start in the same place: LinkedIn. If you are reading this as an engineer rather than the person who arranges training, none of that is your problem: everything that follows is complete as it stands, and easy to forward to a colleague if it seems useful. — Curtis "Ovid" Poe Orientation · Module 1 Who is driving? AI is not magic pixie dust you sprinkle on a problem. It is a tool, and it works best when your engineering judgement drives it rather than the other way around. PAAD is a toolkit for keeping the arrangement pointing in that direction. The section "What PAAD is", two sections below, explains it in full. Developers who use AI coding tools extensively – but don't carefully review their code – discover something unpleasant. The first day feels like magic. The first month is productive. But over time, they notice that the codebase has become a place they no longer recognise. Three different ways of handling errors, a config value hard-coded in two places, tests that pass without asserting anything, and a feature that technically does what they asked but not what they meant. Nothing went dramatically wrong. That is the whole problem. Code quality rarely degrades in one dramatic change; it slips through a series of small decisions that each seemed reasonable in isolation. The assistant did what they asked, every time, and the sum of all those reasonable answers is a codebase carrying debt they never chose to accept. Two arrangements What went wrong there is not really a code-quality problem. It is a question of who was making the decisions. The developer told the assistant what to do and hoped it would take charge. The assistant did as it was told — it always does — and the developer found out what it had decided only once the code was written. That is AI-driven engineering: the assistant sets the pace, and the engineers are downstream of decisions they never saw being made. PAAD — an open-source project for AI coding assistants, explained in full in the next section — proposes the inverse, and its README puts it as a tagline: Engineering-driven AI, not AI-driven engineering.PAAD README Same speed, opposite direction. You see what the AI is about to do while you can still change it, and you make the decisions. Concretely, that means something different happens at each stage of the work. The names in the right-hand column are PAAD's four core skills — things you invoke by name, each with a module of its own later: AI-driven engineeringEngineering-driven AI The specWhatever you typed, unchallengedpushback argues with it before anyone builds it The planAssumed to match the specalignment checks both directions The codeA green CI runagentic-review assigns six specialist reviewers to the PR The structureDiscovered later, expensivelyagentic-architecture finds it while it is cheap The decisionsThe model'sYours, on the record Read the right-hand column downward and you have the shape of the rest of this course. Each module covers one row. What the tagline is not promising Staying in the driver's seat is the point, and it is also the cost. PAAD gives you visibility and control, not autopilot. If what you want is for the assistant to think for you, this is the wrong toolkit — every skill in it ends with a human decision rather than a merge. The README states the consequence plainly: a report you ignore is worse than no report at all. AI coding assistants can compress that process dramatically, but they do not reliably challenge weak requirements, detect drift from the plan, or protect long-term code quality on their own.PAAD README What PAAD is PAAD (pronounced "pad") is an open-source system of AI agent skills — MIT-licensed, on GitHub, created by Curtis "Ovid" Poe. It does not replace your AI-assisted development tools — it complements them, and its README names Superpowers, a separate open-source workflow toolkit for coding agents, as an example of something you can keep using alongside it. Module 3 introduces Superpowers with the other toolkits. The four letters name four common failure modes, and each failure mode has skills that address it. What a "skill" is, since the word is used in a specific way here A skill is a markdown instruction file — conventionally SKILL.md — that your coding assistant loads on demand and follows. It is not code, and it is not a model. It is a written procedure: when the user asks for this, here is how to do it, here is what to check, here is how to report back. Most modern assistants support some version of the format. PAAD is roughly a dozen of them. Throughout this course, a skill written in lowercase means the skill itself — pushback, alignment — and the same word with a leading slash, /pushback, means typing it to your assistant. You can also just ask in plain English. Module 11 covers installing them and the three ways to invoke them; until then, treat the names as labels rather than instructions. P Pushback Weak specs, hidden assumptions, vague requirements, and risky omissions — caught before implementation begins. A Alignment Gaps between requirements, design, implementation plans, and the work that is actually about to happen. A Architecture Structural issues that make code harder to extend, reason about, and maintain over time. D Discipline Consistently applying review, testing, and quality checks instead of skipping them under time pressure. The analogy that makes the idea clear The article introducing the methodology draws a historical parallel worth noting. When Fortran was introduced in the 1950s, IBM knew developers would object, because a compiler could not produce assembler as efficient as hand-written assembler. So the marketing focused on saving developer time, while noting the generated code was almost as fast. It was decades before compilers routinely wrote assembly that ran faster than human-written assembly. Today, very few humans can write assembly code that outperforms a compiler. This is where we are with AI.Curtis Poe, "Watching Claude Sonnet Outperform Opus" The claim is not that AI writes better code than you. The claim is that with discipline — the D in PAAD — it produces code that is almost as good as what you would have written, and produces it in a fraction of the time it would have taken you. The analogy is about how quickly the code gets written, not how quickly it runs. And as with compilers, the quality gap is expected to narrow. It is a good analogy, and like all good analogies it should be checked rather than admired. The appendix “How good is the evidence?” does exactly that. The headline result The founding article is titled "Watching Claude Sonnet Outperform Opus." The finding is exactly that: a smaller, cheaper model (Sonnet) running the PAAD process produced better outcomes than a larger, more capable model (Opus) running without it. Methodology beat model capability. It is also a single team's field report, relayed second-hand, with no control condition — and the Sonnet/Opus contrast was accidental rather than designed, arising because an IDE bug temporarily locked the team out of Opus. The article's own verdict is the right one: "a 'boots on the ground' report from one team, not a benchmark." Keep that in mind. The appendix “How good is the evidence?” sets it against the independent research. What this course covers You will work through the four letters in order, then assemble them into the per-feature loop that ties them together. Two modules do something other than advance that argument. Module 3 is prerequisite rather than PAAD-specific: it explains spec-driven development, the practice PAAD assumes you are already following — skip it if you run spec-kit, Kiro, or OpenSpec today and know why. Module 4 stops to ask what the model cannot see no matter how carefully you review its output. Along the way there are knowledge checks — they are not graded, they exist because reading about a review process and being able to run one are different skills. There is a final assessment at the end. After the assessment there are optional appendices. One of them, “How good is the evidence?”, tests the whole argument against the independent research literature. Nothing in the course depends on any of them and no assessment question draws on them — take the methodology on trust if you prefer, and go there when you want to kn [truncated for AI cost control]