Skip to content

About

Dirty Code: Writing Code for AI Readers — a book in progress. The reader of code has changed from people to AI. (한국어판: AI 시대 / 더티 코드)

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

70 Commits

Folders and files

Repository files navigation

Cover of Dirty Code: Writing Code for AI Readers. A rainbow tangle of spaghetti code writes the title.

IN THE AGE OF AI

Dirty Code

English  ·  한국어

AI writes the code. People write the guarantees.
We learned to write code for people. Now we write it for AI.


Pop the hood and all you see is a cover

On an older car, you opened the hood and saw the parts. You could see a worn belt or an oil leak, and you fixed it with a wrench.

Open the hood of a modern car and you see a plastic cover. You can't tell what's wrong by looking. But plug a scan tool into the diagnostic port under the dashboard, and the fault comes up as a code, such as "P0303: cylinder 3 misfire." Nobody built the car carelessly. Mechanics now plug in the scan tool before they look, so cars are built for the scan tool to read.

The same thing is happening to code. Of the code merged into your repository today, how many lines did you read one by one? When you tell an AI "fix this bug," the one who finds the related code and reads it first is the AI, not you. This book starts there. When you hand a task to an AI, the AI reads your code before you do.

Dirty Code is about writing code that this reader, the AI, can read and change well. It is also about what people should do instead, once they stop reading code line by line.

Mechanics call the fault codes on a scan tool DTCs: Diagnostic Trouble Codes.
In this book, DTC stands for Dirty Code.

Three questions

  1. What does code look like when AI can read it and change it well?
    Names, where code lives, duplication, comments, error messages, folder structure, and prompts. (Part II)
  2. If people no longer read the code, how do they guarantee quality?
    They split the work, decide what must never break, and design how to check it. (Part III)
  3. Is it true, and how far does it go?
    We build the same feature in two shapes, ask AI to change both, and compare the numbers. We also cover the moments when people still have to read the code. (Part IV)

This book does not cover how to use AI tools, model rankings, or the future of jobs.

Contents

Chapters are posted here as drafts while the book is being written. A linked title is a draft you can read now. No experiment has been run yet. Each chapter's Evidence section says what its experiment will measure.

Preface. To Clean Code: we learned to write code for people · draft

Part I. The reader of your code has changed

  1. "My way used to be faster": the day developers stopped reading code · draft
  2. AI doesn't remember the code it read yesterday · draft
  3. What carries over from Clean Code, and what changes · draft

Part II. Code for the scan tool

  1. AI guesses what a function does from its name · draft
  2. Keep what changes together on one screen · draft
  3. When a copy is safer than a shared function · draft
  4. Comments say why: AI tidies up numbers it can't explain · draft
  5. Every hop through a function is a chance for AI to get lost · draft
  6. Install a diagnostic port: errors and logs for AI to read · draft
  7. The map AI navigates by: folder names and an index file · draft
  8. Prompts are code that AI reads · draft

Part III. People install the warning lights

  1. Where to cut: hand off work in pieces you can check · draft
  2. People decide what must never break when things run at once · draft
  3. How to check code without reading a line of it · draft
  4. How to have AI inspect the code AI wrote · draft

Part IV. Is it true, and how far does it go?

  1. The experiment: one feature, two engine bays · draft
  2. When the GPS is wrong: the moments people must read code · draft
  3. Can we skip the code? We asked AI to write machine code directly · draft

Closing. AI writes the code. People write the guarantees. · draft

Every chapter follows the same order

  1. Scene: a situation everyone has been in
  2. Claim: one sentence
  3. Why: derived from "AI has no memory, so it reads your code for the first time, every time"
  4. Code: a concrete example, usually the version for people next to the version for AI
  5. Prompt: what AI opened and changed when given the same task
  6. Evidence: an experiment or a case from real work
  7. What people do: something you can do tomorrow
  8. Where it breaks: the cases where the claim does not hold

Every claim comes with an experiment

  • We build the same feature in two shapes. The behavior and the tests are identical. Only the shape of the code differs.
  • We send the same request to a fresh session at least ten times.
  • Success is judged by tests the AI never sees.
  • Every result is recorded with its date and model name, because the numbers change when the model changes.

The experiment plan is in experiments/ (in Korean for now).

On Clean Code

Robert C. Martin's Clean Code set the standard for code that people read. Today's AI learned to code from code that people wrote, so for now clean code is easy for AI to read too. But as code gets arranged for what is most effective and efficient for an AI reader, it will look less and less like clean code. This book calls that code dirty code. Where its advice differs from Clean Code's, the book says so. Some things, like names and tests, matter even more.

Status

  • November 2026: the outline and experiment plan are set, and writing has begun. The English draft of the whole book is posted: the preface, 18 chapters, and the closing. A Korean draft of every chapter is posted too, linked from the Korean front page. The experiments have not been run yet.
  • The manuscript was written in English first. The Korean draft is rewritten for Korean readers from the English one.

New chapters will appear in this repository. Turn on Watch to hear about them. A Star tells the author how many readers are waiting.

About the author

Wooyong Lee spent more than five years catching fraud and money laundering at Korean crypto exchanges, including Bithumb and Digital X. No one can read every transaction an exchange handles in a day, so he wrote rules that read them and flagged what looked wrong. Today he builds AI agents in Seoul, and AI writes much of the code he works with. Dirty Code takes the same approach to code.


© 2026 Wooyong Lee. All rights reserved. Please credit the source when quoting.

About

Dirty Code: Writing Code for AI Readers — a book in progress. The reader of code has changed from people to AI. (한국어판: AI 시대 / 더티 코드)

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages