How Marcel Bruckner builds software

The standing rules for every repository: how an app is shaped, how code is written, how a repository is set up and which stacks it uses. Each says why it exists and what it rules out, and names a repository where it is done.

Read the conventions Use them in Claude Code

They are written for people and for Claude alike: the same pages ship as a Claude Code plugin, so a session loads the ones that apply before it designs, builds, sets up or reviews code.

The repository wins

A repository's own CLAUDE.md, values page and ADRs override these conventions where they differ. A repository that follows them says so in its CLAUDE.md: "Follows Marceltov/engineering-conventions; the rules here win where they differ."

The conventions

Architecture

• MCP first, one domain layer: MCP, REST and the web pages call the same framework-free domain layer; every tool result carries next.
• One gate for every read: privacy, scoping or spoilers are one function every read goes through.
• Sign-in: Better Auth for apps with a web UI, mcp-login-oauth for form-login MCP servers, backends check tokens.

Code

• Language: code, logs and docs in English; UI text from one copy file.
• HTTPS clients trust the OS certificate store: truststore, not certifi's bundle.
• Formatting and linting: 160 columns everywhere; Prettier, and Ruff for Python, from shared config files; CI checks.

Repository setup

• CLAUDE.md: commands, architecture and rules for every session.
• Values and roadmap pages: what a project stands for and where it is going.
• Architecture decisions: MADR files in docs/adr/.
• Documentation site: Material for MkDocs on GitHub Pages, each site with its own design; short READMEs.
• Diagrams: sequences, flows and structures as small Mermaid diagrams, in the site's palette, with a sentence of reading.
• Dependabot with auto-merge: small bumps merge once CI is green.
• Releases: a version tag builds the image and the release.

Working with Claude

• Working rules for Claude sessions: small tool output, narrow reads and searches, no unasked subagents, short replies; in every session from its start.

Stacks

• Next.js app, SQLite, Better Auth, mcp-login-oauth, Python and FastMCP.

How a page reads

Every convention has the same shape, so it can be used in a review:

1. The rule, in bold, in one or two sentences.
2. Why: the problem it solves, often an incident or a decision with its date.
3. How: what to do, concretely enough to follow without asking.
4. Rules out: what a change must not do. This is the line a review cites.
5. Reference: a repository where it is done right.

What these conventions stand for, and how they change, is on What engineering-conventions stands for.