Terturionsland
02Blog

De documentatie die ontbreekt

Aantekeningen over wat we al bouwend leren. Bijna alles komt uit een concreet probleem dat ons meer tijd kostte dan verwacht.

Alle
  1. ProductoLa web de un pintor solo tiene que hacer una cosa: que le llamenHice la web y la app de trabajo de Mamu, un pintor de Valencia, en cuatro días sueltos. Lo que más mejoró la web fue borrar las páginas de precios y de por qué elegirnos.
  2. IACómo construimos Zenbu, un buscador de anime que busca por lo que cuentasCatorce mil animes, un vector por serie y un LLM que reordena al final. Lo que más nos costó no fue la búsqueda semántica: fueron las secuelas con sinopsis de una línea.
  3. ArchitectuurIk ben vier keer van auth-provider gemigreerdVier managed providers in anderhalf jaar, en overal dezelfde bestemming: eigen middleware. Wat er bij elke overgang breekt en waar ik nu naar kijk voordat ik één regel auth schrijf.
  4. OperatieStripe heeft mijn build vijf keer gebroken en nu staat het in de agendaDe API-versie van Stripe ophogen is geen incident. Het is terugkerend onderhoud, met redelijk voorspelbare nevenschade, en je kunt het maar beter begroten.
  5. ProductCredits, saldo, uitgavenlimietenIn vijf producten heb ik de facturering per gebruik op dezelfde manier gebouwd: ik begin met credits en eindig met saldo in centen en limieten per sleutel. Inmiddels weet ik in welke fase ik moet beginnen.
  6. DatabasesWaarom ik RLS uit Postgres heb gehaald, beide keren dat ik het gebruikteRow Level Security lijkt de juiste standaardpraktijk. Met Drizzle, server actions en eigen auth woont de permissielogica al ergens anders, en beide onderhouden doet pijn.
  7. OordeelIk begin nooit bij nul: wat ik altijd meeneem en wat ik altijd wegsnijTien projecten op dezelfde boilerplate. De eerste commit van elk lijkt meer op de laatste van het vorige dan op een nieuw project, en de tweede commit verwijdert bijna altijd iets.
  8. OordeelHet eerste wat ik uit elke template haal is StripeIk begin bijna elk project met het verwijderen van de checkout, het portaal en de webhook. Geen verstrooidheid: het is de infrastructuur die ik altijd nodig ga hebben scheiden van wat nog niet aan de beurt is.
  9. ArchitectuurDezelfde concurrency-bug is me in drie verschillende projecten overkomenEen teller die onder belasting optelt verliest verhogingen, en een die aftrekt kan hetzelfde twee keer in rekening brengen. Als de teller geld is, is dat geen detail dat je later oplost.
  10. AIElk nieuw model breekt iets anders bij meZes modelmigraties in anderhalf jaar. Geen enkele was het veranderen van een tekstregel, ook al leek het er steeds op.
  11. DatabasesIk heb hetzelfde contractenmodel meer dan tien keer herschrevenEen ingewikkeld domeinmodel komt er niet in één keer goed uit. Je convergeert ernaartoe door het te herschrijven met de echte data voor je, en daar hoort bij dat je beslissingen terugdraait die juist leken.
  12. DatabasesMijn eerste dataschema's overleven de eerste maand bijna nooitHet schema van dag 1 is een hypothese over een domein dat je nog niet begrijpt. Dat aannemen verandert hoe je het schrijft en hoeveel pijn het doet om het te veranderen.
  13. BeveiligingWaarom ik gasttoegang met een sessietoken doe en niet met codesEen code van zes cijfers lijkt de simpele manier om iemand zonder account binnen te laten. Dat is het ook, totdat je hem moet intrekken en ontdekt dat je niet weet wie je eruit gooit.
  14. OperatieWaarom "het werkt lokaal" me niets meer zegtDe verschillen tussen jouw machine en productie zijn geen pech: het zijn vier concrete categorieën die altijd misgaan en die een groene build niet kan zien.
  15. TechniekDe test die groen zei en loogZes SCRIPT ERROR binnen een test die ALLE TESTS OK afdrukte en afsloot met code 0. Hoe je ontdekt dat een groen vals is en wat ik nu doe voordat ik er een vertrouw.
  16. PerformanceAdminlijsten zijn het eerste wat omvaltHet interne paneel wordt zonder limieten geschreven omdat er in het begin vier rijen zijn. Precies daar knapt alles als het product groeit.
  17. BeveiligingWat ik leerde door mijn eigen code te auditen alsof die van iemand anders wasEen lege ACL die het hele corpus teruggaf, een CSS-injectie zonder één regel JavaScript en een API key die bleef werken nadat de eigenaar was opgezegd. Alles op één dag, alles in code die ik zelf had geschreven.
  18. ArchitectuurWaarom ik login eis in apps die het niet nodig hebbenZonder identiteit is er geen quotum, geen uitgavenlimiet, en geen manier om misbruik af te kappen. De frictie van registreren is goedkoop vergeleken met wat het kost om het niet te hebben.
  19. OordeelWat er altijd gebeurt als ik iets met de hand beginIk heb vier keer met de hand een editor gebouwd. Drie ervan zijn herschreven met een library. De vierde haalde de twee dagen niet.
  20. FrontendWanneer een globale store zijn plek verdientGlobale state rechtvaardig je niet met gemak. Je rechtvaardigt het wanneer een tussenliggende component props krijgt die hij niet gebruikt, alleen om ze door te geven naar beneden.
  21. OordeelVijf migraties van ESLint naar Biome: de beslissing is al genomenAls je dezelfde migratie in vijf projecten doet zonder er nog over na te denken, is het geen voorkeur meer maar een oordeel. Wat er onderweg stukgaat en wat je kwijtraakt.
  22. OordeelDocumenteren vóór programmeren: mijn regel voor integraties die ik niet beheerBij een integratie met een externe API raken de eerste vier commits geen code aan. Het document eerst schrijven dwingt je de limieten te meten die je later in productie opblazen.