What makes good code? I used to not know the answer to that honestly.
And how to learn to code the right way, with AI? What are the things to think about?
Tldr is that you can use claude superpower’s brainstorm skill and other tools to research fast. Stay updated with some newsletters. Now we need to think more as managers, but understanding code and what’s happening is crucial, if you don’t learn this you’ll be replaced, this is how you can push it to its optimisation limits.
https://jshingler.github.io/blog/2025/10/25/package-by-feature-vs-clean-architecture/
Codegraph, ponytail help a lot.
Also check out my claude code setup
However a sad truth is that as AI gets better we probably won’t even need that. But the idea aspect will always matter. If you care about something (maybe you need the product) you can push it to its limits and make it great.
Comments about why things exist are great. In this age of AI they’re probably even necessary.
The rule that makes them worth writing: a comment says why, never what. The what is already in the code — if the code doesn’t say it, fix the code. The why can’t be recovered from the source at all. The constraint you worked around, the bug that made the obvious approach wrong, the reason this is ordered the way it is: none of that survives unless someone writes it down.
So you want to code with AI has good external resources to make up your mind about this.
And code is only as good as the documentation that comes with it Documentation
https://www.youtube.com/watch?v=cSbfRspRu2E they mention boot.dev which doesn’t seem that bad to me, and https://sre.google/books/ and https://github.com/awesome-selfhosted/awesome-selfhosted are good for theoretical and practical knowledge.
Documentation
There isn’t one thing called documentation. There are four, they serve different readers, and mixing them is why most documentation is bad. From Daniele Procida’s Divio system:
| Study (learning) | Work (doing) | |
|---|---|---|
| Practical | Tutorial | How-to guide |
| Theoretical | Explanation | Reference |
- Tutorial — a lesson. Takes a beginner by the hand to a finished, working thing so they learn that they can. Must work every time, and show a visible result at every step. No alternatives, no options, no theory, no best practices — each of those stalls a beginner. Teaching a child to cook; the dish barely matters.
- How-to guide — a recipe. Answers a question only someone with some competence can even ask. Titled
How to <do the thing>, never a noun phrase like “Class-based views”. Practical usability beats completeness: it may start mid-process and link out for concepts. Assumes you can already cook. - Reference — the encyclopedia entry. Describes the machinery: classes, functions, parameters, errors, config keys. Mirrors the structure of the codebase, so you can navigate code and docs together — which also exposes what’s gone stale. Austere and consistent. No teaching, no opinion. An entry on ginger tells you what ginger is, not what to cook with it.
- Explanation — the why. Context, design decisions, the constraints that forced them, the alternatives rejected and the trade-offs. Read at leisure, away from the keyboard. Opinion belongs here, and only here. A book on the history and science of cooking.
The cardinal rule
Never mix two quadrants in one document. Almost every documentation failure is a quadrant violation: explanation smuggled into a tutorial (the beginner stalls), how-to steps buried in reference (the fact becomes unfindable), a tutorial that pauses to offer three alternatives (the learner now has to make a decision they lack the knowledge to make). When a section starts serving a second quadrant, cut it out and link to it.
Where each one lives:
| Quadrant | Home |
|---|---|
| Introduction | README.md — what this is, why you should care, then links out. A doorway, not a manual. |
| Tutorial | docs/tutorials/ — usually just one, “getting started” |
| How-to | docs/how-to/ — grows over time, one per real question |
| Reference | docs/reference/, mirroring source layout, or generated from types/docstrings |
| Explanation | docs/explanation/, ADRs, WHY.md |
Two that carry more weight than they look:
WHY.md— why this project should exist at all. Pure explanation. Written before the code, not after. This is batman’s ritual, and it’s the cheapest thing on the list.- ADRs — one architectural decision per file, dated, including the options you rejected. The cheapest defence against re-litigating a settled decision six months later — which is exactly the argument you will otherwise keep having with an AI that has no memory of it.
Practical rules: update reference in the same commit as the code, or it becomes a liability. Don’t write a tutorial against an unstable API — it will break and burn trust. And the second time you explain something in chat, it’s a how-to you haven’t written yet.
My claude code setup wires this in as a reference file that the code skill loads only when it’s actually writing docs.