Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/guidomantilla/best-practices

Curated software engineering best practices. Backend, Frontend, Data, AI Engineering. Zero Trust (CISA ZTMM) + Well-Architected frameworks. Claude Code skills included.
https://github.com/guidomantilla/best-practices

ai-engineering architecture backend best-practices ci-cd claude-code data-engineering frontend observability secure-coding software-engineering system-design testing well-architected zero-trust

Last synced: about 1 month ago
JSON representation

Curated software engineering best practices. Backend, Frontend, Data, AI Engineering. Zero Trust (CISA ZTMM) + Well-Architected frameworks. Claude Code skills included.

Awesome Lists containing this project

README 

          
# Best Practices



A curated knowledge base of software engineering best practices. Organized by engineering domain, with cross-cutting security and architecture frameworks.



## What this repo IS



- A **proxy/index** of best practices — enumerates what to consider, references canonical sources (OWASP, CWE, NIST, CISA, Kimball, GoF, etc.)

- **AI-assisted consultation against a curated knowledge base** — the skills query this content to produce narrative findings, gap analysis, and roadmaps

- **Opinionated where it matters** — takes a position on trade-offs, anti-patterns, and tooling choices

- **Written for developers** — deep on what devs own, lighter on what infra/platform teams own

- **Multi-domain** — backend is the canonical base, other domains reference it and add domain-specific content

- **AI-readable** — structured for use by AI coding assistants (Claude Code skills included)



## What this repo is NOT



- Not a tutorial or step-by-step guide

- Not a source of truth — it references sources of truth (OWASP, NIST, etc.), not replaces them

- Not framework-specific — principles are language/framework-agnostic (tooling is mentioned as examples)

- Not exhaustive — covers the most impactful practices, not every edge case

- Not static — evolves with the industry (content is dated 2026, reviewed for currency)

- **Not a substitute for static analyzers.** The repo recommends specific analyzers per language/topic — the analyzers enforce, this repo helps decide *what* to enforce.

- **Not a PR review bot.** Skills are not designed for automated per-PR runs in CI. Output varies between invocations.

- **Not a quality gate.** Severity labels (High/Medium/Low) are reading aids, not thresholds for automated blocking.

- **Not language-specific.** No *Effective Java*, no *Idiomatic Go*, no *Clean Code* book content, no PEP 8 detail. Those exist; this repo references them as tools, doesn't replace them.

- **Not opinion-free.** "Opinionated" means the author has taken positions on trade-offs. Read positions as informed opinion, not industry consensus.

- **Not a playbook.** Lists what to consider, not what to do in order.



## How this compares to tools you may know



If you've used the tools below, this is how they relate. They are complementary — none replaces another.



| Tool | What it is | Output | When to use |

|---|---|---|---|

| SonarQube · Semgrep · ruff · gosec | Static analyzer with deterministic rules | Reproducible findings, exit codes | In CI, every commit |

| Greptile · CodeRabbit · SonarCloud | AI bot for PR review | Line-by-line diff comments | On every PR |

| **best-practices skills** | LLM consultation against a curated knowledge base | Narrative findings + roadmap + tooling recommendations | On demand, exploratory |

| *Effective Java* · *Clean Code* · *Idiomatic Go* | Reference book | Text the dev reads | Onboarding, critical reading |



This repo does not compete with static analyzers — it tells you which ones to wire up. It does not compete with PR bots — it works on whole codebases, not diffs. It does not replace books — it points to them.



---



## Structure



### Engineering Domains



| Domain | Description | Status |

|---|---|---|

| [`backend-engineering/`](backend-engineering/README.md) | **Canonical base.** 11 topics: secure coding, software principles, observability, configuration, testing, CI/CD, IaC, contract design, system design, data design, data privacy. | Complete |

| [`frontend-engineering/`](frontend-engineering/README.md) | 7 domain-specific topics + references to backend for shared content. Covers: secure coding (XSS, CSP, cookies), observability (RUM, CWV), system design (SPA/SSR, state, BFF), testing (component, visual, a11y), frameworks (React/Vue/Angular/Svelte/Astro), configuration (no secrets in client), API consumption. | Complete |

| [`data-engineering/`](data-engineering/README.md) | 5 domain-specific topics + references to backend. Covers: secure coding (PII in pipelines, masking), observability (freshness, lineage, quality metrics), testing (data quality, schema validation, contracts), contract design (schema registry, compatibility), system design (batch/streaming, dimensional modeling, lakehouse, data mesh). | Complete |

| [`ai-engineering/`](ai-engineering/README.md) | 7 domain-specific topics + references to backend. Building apps WITH AI models (LLMs, multimodal). Covers: secure coding (prompt injection, guardrails, OWASP LLM Top 10), observability (tokens, cost, quality, drift), testing (AI-as-judge, adversarial, eval datasets), CI/CD (CI/CT/CD, model registry, A/B), configuration (model params, prompts as config), contract design (streaming, tool_use, structured outputs), system design (RAG, agents, MCP, extended thinking, fine-tuning, inference optimization). | Complete |

| [`ml-engineering/`](ml-engineering/) | Training and adapting models (not using them). | Pending |



### Cross-Cutting Frameworks



| Framework | Description | Status |

|---|---|---|

| [`zero-trust/`](zero-trust/README.md) | CISA Zero Trust Maturity Model v2 + NIST SP 800-207. 5 pillars (Identity, Devices, Networks, Applications, Data) + 3 cross-cutting capabilities. Developer-focused — deep on identity/apps/data, lighter on devices/networks. | Complete |

| [`well-architected/`](well-architected/README.md) | Synthesized from AWS/Azure/GCP Well-Architected Frameworks + Bass (*Software Architecture in Practice*) + Richards/Ford (*Fundamentals of Software Architecture*). 5 pillars + architecture methodology (QA scenarios, ADRs, fitness functions, trade-off analysis, cost optimization). | Complete |



### Skills (Claude Code)



| Folder | Description |

|---|---|

| [`.skills/`](.skills/) | 10 Claude Code skills with automatic domain detection (backend/frontend/data/AI). Each skill reads the appropriate reference files based on the code being reviewed. |



Available skills: `assess-secure-coding`, `assess-coding-principles`, `assess-observability`, `assess-configuration`, `assess-testing`, `assess-ci-cd`, `assess-iac`, `assess-contract-design`, `assess-system-design`, `assess-data-design`. Plus `overview` for in-session discovery — supports three modes: default catalog, advisory (`--ask` to recommend a skill), and how-to (`/overview ` for usage of one specific skill).



---



## About the skills



What to expect when you invoke a skill.



- **Consultative, not prescriptive.** Output is a starting point for conversation, not a verdict. The skill says "consider X, here's why" — you decide what to do.

- **Auto-domain detection.** Skills inspect imports and file patterns to figure out whether you're in backend, frontend, data, or AI code, and read the right slice of the knowledge base accordingly.

- **Defined scope.** Each skill is bounded. `assess-coding-principles` evaluates *how* code is written, not *what* exists; it cannot tell you what to build next. Combining skills covers more ground than asking one skill to do everything.

- **Predictable naming.** Every skill is `assess-` (e.g. `assess-secure-coding`, `assess-iac`). Once you know the pattern, the slash for any topic is guessable. The `overview` skill is the one exception — it's a discovery entrypoint, not an assessment.



## Invocation patterns



Output quality depends heavily on how you prompt the skill. The same skill produces a quick checklist, a phased roadmap, or a planning conversation depending on what you ask for. Seven patterns cover the useful range — each `assess-*/SKILL.md` lists concrete examples for that skill, but the underlying patterns are universal.



| # | Pattern | Invocation | Output | When to use |

|---|---|---|---|---|

| 1 | **Blind** (default) | `/assess-secure-coding` | Checklist of findings with severity. Fast, broad. | You know the codebase, want a quick scan. |

| 2 | **Scoped** *(first-class)* | `/assess-secure-coding src/auth/` | Same output, restricted to that path. If no path is given, the skill drops a one-liner reminder that you can scope. | You want to limit attention to a part of the codebase. |

| 3 | **Narrative context** | `/assess-secure-coding este es greenfield, foco auth, datos PHI` | Findings adapted to the context you stated (stage, domain, constraints). | You want the skill to understand *what* you're building before judging it. |

| 4 | **Roadmap-driven** | `/assess-testing dame un roadmap por fases con días estimados` | A phased plan instead of a finding list — what to build first, second, etc. | You want guidance, not audit. Onboarding, greenfield projects, post-incident planning. |

| 5 | **Conversational / intake-first** *(first-class)* | `/assess-secure-coding --ask` *or* `/assess-secure-coding preguntame el contexto antes de empezar` | Skill asks 4 generic + 1–2 skill-specific questions, then emits a tailored review. Waits for answers before reading files. | You want the skill to drive the context discovery. |

| 6 | **Deterministic** | `/assess-secure-coding and after the review, generate me a scanning script with the recommended tools` | LLM review (non-deterministic) + a runnable scanning script (deterministic, CI-ready). | You need a reproducible CI gate — see [Reproducibility](#reproducibility--what-to-expect-what-to-do) for the full pattern. |

| 7 | **Plan-first** | `/assess-system-design ... confirma cómo procederás antes de arrancar` | Skill responds with a structured plan (phases, files it will read, what it will NOT do) and waits for explicit "procede" before consuming tokens. | You want to align expectations BEFORE a 3–5 minute long review. Cheap to redirect; surfaces wrong assumptions early. |



These compose. A common combination is **scoped + narrative + roadmap-driven**: `/assess-secure-coding src/auth/ greenfield, datos PHI, dame un roadmap`.



### Progress reporting



Long invocations (3–5 minutes) announce progress at two levels so you can see the skill is alive and roughly where it is:



- **Stage** (3 top-level): *"Exploring codebase..."*, *"Cross-referencing knowledge base..."*, *"Compiling findings..."*

- **Area** (within each stage): *"Reading auth handlers (3 files)..."*, *"Loading backend-engineering/secure-coding/..."*



This applies to every skill — no flag needed.



### What context can skills consume?



When you reference external material in the prompt, this is what works today:



| Format | Supported? | How |

|---|---|---|

| Source code (`.py`, `.go`, `.ts`, …) | Yes | Native via Read |

| Markdown (`.md`) | Yes | Native |

| URLs (HTTP) | Yes | Via WebFetch — may not bypass auth |

| PDFs | **Not natively** | Convert first: *"convertí el PDF con `pdftotext` y luego procesalo"*. Without instruction, PDFs are silently ignored. |

| Confluence, Jira, Notion | Only with MCP | Requires the corresponding MCP server configured in the user's environment |



If a skill encounters input it cannot process today, it may silently skip it. When in doubt, mention the file format explicitly and how it should be handled.



## Reproducibility — what to expect, what to do



> **Skill output is non-deterministic.** Skills are powered by LLMs. Same skill + same code + same prompt can produce slightly different findings between runs. This is a feature (the skill adapts to context) and a limitation (you cannot diff outputs to detect regressions like you would with `ruff` or `gosec`).

>

> **Implications:**

> - Use static analyzers (recommended in the topic READMEs) for reproducible CI gates.

> - Use these skills for exploration, onboarding, gap analysis, and architectural conversations — not for automated quality enforcement.



### What to do if you need determinism



Don't invoke skills in CI. Pair them with deterministic tools instead:



1. Invoke the skill **once** locally to get a review.

2. Ask the skill to **generate a scanning script** with the tools it recommends for your stack (every skill offers this in its `What I Can Generate` section).

3. Use the **script** in CI. The script is deterministic. The skill is exploratory.



| Use case | What to use |

|---|---|

| Exploration, onboarding, gap analysis, architecture conversations | Skill |

| Pre-merge gate, CI, compliance audit | Generated script (with tools the skill picked for your stack) |

| Continuous dashboard | Skill output to seed the dashboard; scripts to keep it updated |



Skills fall into three categories by how much of their scope can be delegated to deterministic tools. The category lives in each skill's frontmatter (`category:`) and shows up in the table below.



- **Tool-backed**: a deterministic tool fully covers the skill's scope. Treat the skill as a one-time advisor, then run the script in CI.

- **Hybrid**: some aspects deterministic, others LLM judgment. Use the script in CI for the deterministic part; keep invoking the skill for the rest.

- **LLM-pure**: no deterministic counterpart exists; non-determinism is the feature. Don't try to put this in CI — its value is the conversation.



| Skill | Category | Deterministic counterpart |

|---|---|---|

| `assess-iac` | tool-backed | Checkov + Trivy + tfsec scan workflow |

| `assess-configuration` | tool-backed | Schema validation + secret-detection script |

| `assess-secure-coding` | hybrid | `security-scan.sh` (semgrep / bandit / gosec / etc.) |

| `assess-testing` | hybrid | CI workflow with coverage thresholds + flake detection |

| `assess-observability` | hybrid | CI check that flags handlers without instrumentation |

| `assess-data-design` | hybrid | SQL/schema lint + slow-query (EXPLAIN) regression check |

| `assess-ci-cd` | hybrid | Pipeline-files lint workflow |

| `assess-contract-design` | hybrid | Spectral / buf / graphql-eslint validation in CI |

| `assess-coding-principles` | LLM-pure | Complexity report (partial — flags structural smells only) |

| `assess-system-design` | LLM-pure | Fitness functions (architecture tests) — see [`well-architected/fitness-functions.md`](well-architected/fitness-functions.md) |



The deterministic counterpart for each skill is the **first** offer in that skill's `What I Can Generate` section.



---



## How the Domains Relate



```

backend-engineering/     ← canonical base (all other domains reference this)

  ├── frontend-engineering/   references backend + adds frontend-specific (XSS, RUM, SPA/SSR, components)

  ├── data-engineering/       references backend + adds data-specific (pipelines, quality, dimensional modeling)

  ├── ai-engineering/         references backend + adds AI-specific (prompts, RAG, agents, eval, guardrails)

  └── ml-engineering/         references backend + adds ML-specific (training, MLOps) [pending]

```



Content that's identical across domains lives in `backend-engineering/` only. Other domains:

- Reference backend for shared content (software principles, CI/CD, IaC, data privacy)

- Create domain-specific files where practices differ

- Don't include topics that don't apply (frontend has no data-design, for example)



---



## How to Use This Repo



### As a developer (human)

1. Start with your domain (`backend-engineering/`, `frontend-engineering/`, etc.)

2. Each domain has a README that maps topics → files

3. Each file is self-contained with principles, anti-patterns, and tooling

4. Cross-references point to related content (never required — each file stands alone)



### As an AI coding assistant

1. Read the relevant domain README to understand structure

2. Read specific topic files based on the review/task at hand

3. Skills in `.skills/` are pre-built prompts that automate this (domain detection + appropriate file reading)

4. Cross-cutting frameworks (`zero-trust/`, `well-architected/`) provide lens for architectural review



### Installing skills in your project

```bash

# Clone this repo

git clone https://github.com/guidomantilla/best-practices.git



# Install skills into your project (choose your tool)

make install-claude TARGET=~/projects/my-app        # Claude Code

make install-copilot TARGET=~/projects/my-app       # GitHub Copilot

make install-cursor TARGET=~/projects/my-app        # Cursor



# Install only specific skills

make install-claude TARGET=~/projects/my-app SKILLS='assess-secure-coding assess-testing'



# Roll back an install

make uninstall-claude TARGET=~/projects/my-app

make uninstall-all TARGET=~/projects/my-app          # all 3 tools at once



# List available skills

make list

```



### Quick start (after installing)



After `make install-claude`, open Claude Code in your project and try:



**1. Discover what's installed**

```

/best-practices

```

or, in natural language:

```

what best-practices skills do I have here?

```

Claude responds with a catalog of the 10 assessment skills, what each one covers, and when to use it.



**2. Run a focused assessment**

```

/assess-secure-coding src/api/

```

Claude reads the code under `src/api/`, reports concrete vulnerabilities with file:line citations, and references the relevant section of `backend-engineering/secure-coding/` for the rationale.



**3. Ask in natural language**

```

review the testing strategy for this service — are there gaps?

```

Claude auto-invokes `assess-testing`, walks the test pyramid, flags missing levels, and proposes the highest-value tests to add first.



In Cursor and Copilot, the same content is loaded as rules / instructions — invoke by asking the assistant directly (slash commands are Claude-Code-specific).



### For a new project

1. Install skills (see above)

2. `backend-engineering/system-design/methodology.md` — ADRs, trade-off analysis, quality attribute scenarios

3. `well-architected/` — the 5 pillars checklist

4. `zero-trust/` — security posture from day 1

5. Your domain folder — domain-specific best practices



---



## Design Decisions



| Decision | Rationale |

|---|---|

| **Proxy, not source of truth** | Content references canonical sources (OWASP, CWE, NIST). Stable concepts are copied locally (SOLID, CISA ZTMM). Frequently changing content (CVE lists, specific laws) is referenced. |

| **Backend is canonical** | Backend is the foundation of all software. Frontend, data, and AI extend it — they don't exist without it. |

| **Organized by domain, not by topic** | A developer thinks "I'm building a frontend" not "I need the observability chapter". Each domain has its own entry point. |

| **Each file is self-contained** | You can read one file and get value. Cross-references are "for more depth", never "go read this instead". |

| **Anti-patterns alongside practices** | Knowing what NOT to do is as valuable as knowing what to do. Every section has anti-patterns. |

| **Tooling is examples, not prescriptions** | Tools change faster than principles. Mentioned as examples, not mandates. |

| **Skills use relative paths** | Portable — works for anyone who clones the repo, regardless of where they put it. |

| **No sustainability pillar** | AWS-only concept, out of scope for this repo. |

| **No mobile/platform engineering** | Mobile is a different world (not the author's domain). Platform engineering is operations, not code best practices. |

| **Managed vs self-hosted is a trade-off, not a recommendation** | Cloud vendor frameworks recommend managed because they sell managed. This repo presents both sides honestly. |



---



## References (Foundational)



### Standards & Frameworks

- [OWASP Top 10](https://owasp.org/Top10/) · [OWASP API Security Top 10](https://owasp.org/API-Security/) · [OWASP LLM Top 10](https://genai.owasp.org/llm-top-10/)

- [CWE Top 25](https://cwe.mitre.org/top25/)

- [NIST SP 800-207 — Zero Trust Architecture](https://csrc.nist.gov/pubs/sp/800/207/final)

- [CISA Zero Trust Maturity Model v2](https://www.cisa.gov/resources-tools/resources/zero-trust-maturity-model)

- [AWS Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/framework/) · [Azure](https://learn.microsoft.com/en-us/azure/well-architected/) · [GCP](https://cloud.google.com/architecture/framework)



### Books

- Bass, Clements, Kazman — *Software Architecture in Practice* (4th ed, 2021)

- Richards, Ford — *Fundamentals of Software Architecture* (2nd ed, 2024)

- Kleppmann — *Designing Data-Intensive Applications* (2017)

- Hohpe, Woolf — *Enterprise Integration Patterns* (2003)

- Chip Huyen — *AI Engineering* (2025)

- Kimball — *The Data Warehouse Toolkit* (2013)

- Martin — *Clean Code* (2008) · *Clean Architecture* (2017)

- Beck — *Test-Driven Development* (2003)

- Gamma et al. — *Design Patterns* (1994)

- Hunt, Thomas — *The Pragmatic Programmer* (1999)



---



## License



Apache License 2.0 — see [LICENSE](LICENSE).



Copyright 2026 Guido Mauricio Mantilla Tarazona (guidomau / usq0x6e.co). Bogotá, Colombia.