Platform standards
Shared backend conventions and error-code catalogs — ~20–30 codes per service as a starting point. Adoption stayed optional and low.
Lang
- Node.js
- TypeScript
Others
- System design
- Team leadership
Intro
Every service had its own shape — logging, errors, layout. We wanted one manageable baseline so teams did not reinvent the same backend habits on every project. This was before the AI tooling boom; the work was docs, review culture, and concrete catalogs — not generated scaffolds.
Architecture
- 01Conventionsdocs · how we ship backends
- 02Error codes~20–30 / service · strongest win
- 03Review baroptional · not enforced
- 04ADRs / patternsversioning · layout · when it sticks
What I did
- Wrote shared backend conventions (docs) so “how we ship” had a single reference
- Shipped error-code catalogs as the strongest deliverable — ~20–30 error codes per service as a starting point; teams that used them got clearer client and ops surfaces
- Ran architecture reviews for high-risk changes — useful when people opted in; never had enough authority to mandate org-wide adoption
- Coached ICs on ownership and design trade-offs; did not claim high adoption
Hard problems
Standards with low adoption
- Symptom
- Docs existed; most services still shipped with their own layout and error shapes.
- Cause
- Not enough organizational authority to require the standard, and reviews were not thorough or mandatory — opt-in guidance lost to copy-paste deadlines.
- Fix
- Kept the bar teachable (conventions + error catalogs) and applied it where teams chose in. Honest outcome — adoption stayed low; error codes were the piece teams valued most when they did adopt.
Reviews that did not change the default path
- Symptom
- High-risk PRs still landed inconsistent contracts even after “standards” existed.
- Cause
- Review without enforcement reads as advice; authors optimized for ship date when the checklist was optional.
- Fix
- Paired review on early services and short ADRs for decisions that had to stick locally. Still no org-wide mandate — qualitative win only where ownership was already aligned.
Problem
Inconsistent service shapes made the platform hard to manage. The goal was a shared baseline — not a new product UI.
Trade-offs
- Influence without mandate — standards without authority stay optional. We shipped useful artifacts (especially error codes) rather than pretending adoption was high.
- Docs + catalogs over forced scaffolds — error codes (~20–30 / service starting point) beat abstract process; templates alone would not have fixed review discipline.
Outcomes
Conventions documented. Error-code catalogs were the most successful piece. Adoption remained low and optional — stated that way on purpose. Pre-AI-boom engineering process work; no adoption % claimed.