The full doctrine as operational rules

1. 1

   Skills and refactoring under control

   A repeatable, proven pattern is worth closing into a skill — then the agent has a ready tool instead of reinventing it every time. Refactoring is a discipline, not tidying on the side: first green tests as a safety net, then a change of structure without a change of behaviour, then green again. You don’t mix refactoring with new functionality in one commit. When there are no tests to defend the change, you write the tests first.

2. 2

   Data model and normalization

   Data is designed so it doesn’t duplicate and changes easily: lookup values kept in one place, a slug instead of a bare ID where the URL should be readable and durable, an active-row pattern instead of hard-deleting history. Denormalization is sometimes needed for performance, but it’s a deliberate, documented decision, not a side effect of haste. The control question: “if this value changes tomorrow, in how many places do I have to fix it?”. A good answer is “in one”.

3. 3

   Flexibility, scalability, performance

   App layers are separated, and variable behaviours hidden behind feature flags, so the product can grow without being rewritten from scratch. Performance is a discipline of measurement: first you measure and find the real bottleneck, only then optimize — indexes (including partial ones) where queries hurt, an end to the N+1 problem, streaming of large responses instead of loading everything into memory. The choice between “scale to zero” and “always on” you make deliberately, to the traffic profile. Speed is proven with numbers before and after, not by impression.

4. 4

   Operational resilience

   After launch, real users and external systems hit the service — and that’s when it shows whether it’s resilient. Request limits, timeouts and safe boundary values mean that one bad request or a slow dependency doesn’t take down the whole thing. Event handling is idempotent: the same signal received twice doesn’t break the state. You design for a dependency failure, not just the happy path — because an external API will fall over someday, and your service has to survive it with grace.

5. 5

   Visibility and data from the web

   SEO is done properly: hreflang for language versions, structured data (JSON-LD), deliberate E-E-A-T/YMYL where the topic is sensitive, and language parity treated like a test, not a wish. Gathering data from the web, delegating tasks to AI APIs and chatbots are product features with their own contract: scraping that respects limits and costs, tasks to AI described like any other input-output, a chatbot steerable by configuration without another deploy. Each of these must be cheap, predictable and reversible.

Chapters at this level