A personal knowledge base of engineering decisions I've already made — architecture, naming, git hygiene, per-stack conventions — so AI coding agents write code the way I actually want it written instead of improvising a fresh, "reasonable" convention on every project.
This is not a software project — it's a repository of plain Markdown notes, with no application code, no dependency manifest, and no build/lint/test tooling. "Working on it" means editing notes accurately and keeping them internally consistent.
Every note reflects a decision I've actually made and stand behind — never a generic best-practices checklist copied from somewhere else. If a rule is missing, that's a question for me, not something for an agent to infer or fill in.
- Give the agent read access to this directory. It doesn't get imported live into a project — it's a library an agent consults once, at project-definition time.
- During a new project's Spec-Driven Development phase, once the project's shape and stack are understood, use tech-stack-map to confirm (or pick) the stack.
- Read the layers, from most general to most specific — each layer adds to the one before it and never contradicts it:
- 00-global/ — the rules that apply to every stack: engineering-principles, code-review, testing-principles, error-handling-principles, sources-policy, git-conventions, dependency-management, and, for any UI stack, responsive-design.
- The stack's own folder — list it (e.g.
ls 01-mobile/flutter/) and read it in this order:architecture-principles.md,coding-standards.md,code-review.md,testing.md,error-handling.md,sources.md, then the stack's own note (e.g.flutter.md). - The shared and infra notes the project actually uses:
- tailwind-css — every web project.
- rest-api-design — every backend project that exposes a REST API.
- whichever 04-infra/ notes the project pairs with (database, cache, auth, storage, containerization, security).
- Write the project's own conventions from what was read — its
/docs/folder and aCLAUDE.mdthat points at/docs/with plain relative links, never back at this repository. Then verify against the source notes more than once that no rule was dropped, weakened, or contradicted along the way. From that point the project is self-contained: no live dependency on this repo, no cross-repo imports. If a rule here changes later, redo the affected part when it's relevant to do so.
This deliberately replaces an earlier version of this system that used Claude Code's @path import syntax to pull content live into a project's CLAUDE.md. That tied every consuming project to one tool's import mechanism; plain files in /docs/ work with any agent that can read a directory.
00-global/— the notes that stay genuinely stack-agnostic, written once and shared by every stack: engineering-principles, code-review, testing-principles, error-handling-principles, responsive-design, sources-policy, git-conventions, dependency-management, readme-conventions, and tech-stack-map (the decision map, read once per project).01-mobile/— flutter, jetpack-compose.02-web/— angular, vuejs, react, plus the shared tailwind-css (not a stack of its own — read alongside whichever web stack is chosen).03-backend/— aspnet-core, spring-boot, plus the shared rest-api-design (not a stack of its own — read alongside whichever backend stack exposes a REST API).04-infra/— one self-contained note per infrastructure piece: docker, postgresql, redis, keycloak-auth, aws-s3-storage, local-infrastructure, security-practices.
Each mobile/web/backend stack folder bundles only what's specific to that stack — its own architecture-principles.md, coding-standards.md, code-review.md, testing.md, error-handling.md, sources.md, and the stack note itself. The stack files build on the global notes above (code examples, tooling, doc-comment format, mocking mechanics) and link up to them; see "Why the rules are layered" below.
- Every note reflects a decision I've actually made — a missing rule is a question for me, never something to infer.
- Frontmatter + cross-links: each note opens with
--- tags: [...] ---. Related notes are referenced inline, where actually relevant, via plain relative Markdown links with a display alias —[git-conventions](00-global/git-conventions.md)— resolved relative to the file containing the link, so an agent reading raw Markdown can follow the reference with a direct file read, no search needed. - Exception:
04-infra/notes are deliberately self-contained — no cross-links, and no naming of specific stacks (no "ASP.NET Core" or "Spring Boot" mentions). An agent working on infra shouldn't be pulled toward a particular stack or another infra piece it doesn't need. - New note or renamed file → add the corresponding entry to this README's "Structure" section (and, if it's a new top-level category, describe it there too).
- No empty scaffolding: don't create a new folder or stub note "for later." A folder/note is added at the moment it has real content — the rule in engineering-principles, applied reflexively to itself.
- Single source of truth, no duplication. A rule lives in exactly one note; if two notes need the same rule, one links to the other instead of restating it. Global notes never name a stack and carry no language-specific code; stack notes link up to the global ones, never sideways to another stack.
An earlier version copied the whole rule set into every stack folder so an agent working on one stack never read another one's code examples or cross-links. That kept stacks isolated but meant a change to one rule had to be applied by hand to seven files. Now the stack-agnostic prose (naming, DRY/SOLID, comments, definition of done, review process, testing structure, error-handling policy, responsive principle) lives once in 00-global/ — with no code examples and no stack names, so it can't pull an agent toward a stack the project doesn't use — and each stack folder holds only what's specific to it. The agent reads the global layer plus its own stack folder and nothing else, so isolation is preserved without the duplication.
What's still stack-scoped on purpose: architecture-principles.md (each stack's layout and code examples in its own language) and the link lists in each sources.md.
This repository itself is worked directly on main with plain, imperative Conventional Commits (docs: … for nearly everything, since content here is documentation) — it does not follow the two-branch (main/dev) workflow that git-conventions prescribes for the projects consuming this repository. Match the existing commit style (git log) rather than that note's prescriptive policy when committing here.
This lives on my GitHub so it never gets lost — it's the accumulated result of a lot of trial and error — and so anyone curious, a recruiter included, can see exactly how I think about architecture, conventions, and working with AI agents day to day.
Plain, dependency-free Markdown throughout — notes cross-link with relative Markdown links, so it reads fine directly on GitHub or in any editor, no special tooling required.