Best-Practice Codex · Coding Standards
This codex is what every pod in the NeuroStack deck signs up for. It’s lightweight, automatable, and proven across Atlassian, Bugcrowd, and MetaLabs builds.1. Contracts Before Code
- RFC template in Notion + MDX artifact in repo (
/docs/rfcs/<slug>.mdx). - API/schema files generated from source-of-truth (OpenAPI, GraphQL SDL, Zod).
- All code samples in docs compile—use
markdownlint+ custom check to run snippets.
2. Linting Stack
| Layer | Tool | Rule of thumb |
|---|---|---|
| Language | TypeScript strict mode | noImplicitAny, exactOptionalPropertyTypes. |
| Formatting | Biome (prev. Rome) | Replace Prettier + ESLint formatting for consistency. |
| UX | eslint-plugin-jsx-a11y + custom rule for keyboard traps | Run in CI + pre-commit. |
| Security | eslint-plugin-security + Semgrep policy pack | Block PRs when secrets/hardcoded tokens appear. |
3. Review Rituals
- PR title uses [Conventional Commits].
- Description answers: Why? What changed? Testing notes? Rollback plan?
- Screenshots/demo links for UI changes. Include Replay or Loom for complex flows.
- Reviewer rotates weekly; enable
CODEOWNERS+ “shadow reviewer” for mentoring.
4. Definition of Done (per story)
- Tests added/updated (unit + integration + contract when API touched).
- Docs touched if behavior changes (MDX, Storybook, Runbook).
- Telemetry/SLO impact considered; dashboards updated.
- Feature flags + kill switches documented.
5. Measuring Adoption
- Monthly lint failure report (GitHub Insights) + auto-comment suggestions.
- Retro question: “Which standard saved you recently?” Collect stories to keep standards human.