{"id":49675711,"url":"https://github.com/guidomantilla/best-practices","last_synced_at":"2026-05-07T02:39:39.152Z","repository":{"id":355322990,"uuid":"1227646415","full_name":"guidomantilla/best-practices","owner":"guidomantilla","description":"Curated software engineering best practices. Backend, Frontend, Data, AI Engineering. Zero Trust (CISA ZTMM) + Well-Architected frameworks. Claude Code skills included.","archived":false,"fork":false,"pushed_at":"2026-05-03T02:02:03.000Z","size":340,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-03T03:19:29.500Z","etag":null,"topics":["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"],"latest_commit_sha":null,"homepage":"https://usq0x6e.co","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/guidomantilla.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-03T01:02:31.000Z","updated_at":"2026-05-03T02:02:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/guidomantilla/best-practices","commit_stats":null,"previous_names":["guidomantilla/best-practices"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/guidomantilla/best-practices","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guidomantilla%2Fbest-practices","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guidomantilla%2Fbest-practices/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guidomantilla%2Fbest-practices/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guidomantilla%2Fbest-practices/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guidomantilla","download_url":"https://codeload.github.com/guidomantilla/best-practices/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guidomantilla%2Fbest-practices/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32720771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-07T02:14:30.463Z","status":"ssl_error","status_checked_at":"2026-05-07T02:14:29.405Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-05-07T02:39:37.711Z","updated_at":"2026-05-07T02:39:39.138Z","avatar_url":"https://github.com/guidomantilla.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Best Practices\n\nA curated knowledge base of software engineering best practices. Organized by engineering domain, with cross-cutting security and architecture frameworks.\n\n## What this repo IS\n\n- A **proxy/index** of best practices — enumerates what to consider, references canonical sources (OWASP, CWE, NIST, CISA, Kimball, GoF, etc.)\n- **AI-assisted consultation against a curated knowledge base** — the skills query this content to produce narrative findings, gap analysis, and roadmaps\n- **Opinionated where it matters** — takes a position on trade-offs, anti-patterns, and tooling choices\n- **Written for developers** — deep on what devs own, lighter on what infra/platform teams own\n- **Multi-domain** — backend is the canonical base, other domains reference it and add domain-specific content\n- **AI-readable** — structured for use by AI coding assistants (Claude Code skills included)\n\n## What this repo is NOT\n\n- Not a tutorial or step-by-step guide\n- Not a source of truth — it references sources of truth (OWASP, NIST, etc.), not replaces them\n- Not framework-specific — principles are language/framework-agnostic (tooling is mentioned as examples)\n- Not exhaustive — covers the most impactful practices, not every edge case\n- Not static — evolves with the industry (content is dated 2026, reviewed for currency)\n- **Not a substitute for static analyzers.** The repo recommends specific analyzers per language/topic — the analyzers enforce, this repo helps decide *what* to enforce.\n- **Not a PR review bot.** Skills are not designed for automated per-PR runs in CI. Output varies between invocations.\n- **Not a quality gate.** Severity labels (High/Medium/Low) are reading aids, not thresholds for automated blocking.\n- **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.\n- **Not opinion-free.** \"Opinionated\" means the author has taken positions on trade-offs. Read positions as informed opinion, not industry consensus.\n- **Not a playbook.** Lists what to consider, not what to do in order.\n\n## How this compares to tools you may know\n\nIf you've used the tools below, this is how they relate. They are complementary — none replaces another.\n\n| Tool | What it is | Output | When to use |\n|---|---|---|---|\n| SonarQube · Semgrep · ruff · gosec | Static analyzer with deterministic rules | Reproducible findings, exit codes | In CI, every commit |\n| Greptile · CodeRabbit · SonarCloud | AI bot for PR review | Line-by-line diff comments | On every PR |\n| **best-practices skills** | LLM consultation against a curated knowledge base | Narrative findings + roadmap + tooling recommendations | On demand, exploratory |\n| *Effective Java* · *Clean Code* · *Idiomatic Go* | Reference book | Text the dev reads | Onboarding, critical reading |\n\nThis 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.\n\n---\n\n## Structure\n\n### Engineering Domains\n\n| Domain | Description | Status |\n|---|---|---|\n| [`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 |\n| [`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 |\n| [`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 |\n| [`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 |\n| [`ml-engineering/`](ml-engineering/) | Training and adapting models (not using them). | Pending |\n\n### Cross-Cutting Frameworks\n\n| Framework | Description | Status |\n|---|---|---|\n| [`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 |\n| [`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 |\n\n### Skills (Claude Code)\n\n| Folder | Description |\n|---|---|\n| [`.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. |\n\nAvailable 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 \u003cskill-name\u003e` for usage of one specific skill).\n\n---\n\n## About the skills\n\nWhat to expect when you invoke a skill.\n\n- **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.\n- **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.\n- **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.\n- **Predictable naming.** Every skill is `assess-\u003cdomain\u003e` (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.\n\n## Invocation patterns\n\nOutput 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.\n\n| # | Pattern | Invocation | Output | When to use |\n|---|---|---|---|---|\n| 1 | **Blind** (default) | `/assess-secure-coding` | Checklist of findings with severity. Fast, broad. | You know the codebase, want a quick scan. |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n\nThese compose. A common combination is **scoped + narrative + roadmap-driven**: `/assess-secure-coding src/auth/ greenfield, datos PHI, dame un roadmap`.\n\n### Progress reporting\n\nLong invocations (3–5 minutes) announce progress at two levels so you can see the skill is alive and roughly where it is:\n\n- **Stage** (3 top-level): *\"Exploring codebase...\"*, *\"Cross-referencing knowledge base...\"*, *\"Compiling findings...\"*\n- **Area** (within each stage): *\"Reading auth handlers (3 files)...\"*, *\"Loading backend-engineering/secure-coding/...\"*\n\nThis applies to every skill — no flag needed.\n\n### What context can skills consume?\n\nWhen you reference external material in the prompt, this is what works today:\n\n| Format | Supported? | How |\n|---|---|---|\n| Source code (`.py`, `.go`, `.ts`, …) | Yes | Native via Read |\n| Markdown (`.md`) | Yes | Native |\n| URLs (HTTP) | Yes | Via WebFetch — may not bypass auth |\n| PDFs | **Not natively** | Convert first: *\"convertí el PDF con `pdftotext` y luego procesalo\"*. Without instruction, PDFs are silently ignored. |\n| Confluence, Jira, Notion | Only with MCP | Requires the corresponding MCP server configured in the user's environment |\n\nIf 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.\n\n## Reproducibility — what to expect, what to do\n\n\u003e **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`).\n\u003e\n\u003e **Implications:**\n\u003e - Use static analyzers (recommended in the topic READMEs) for reproducible CI gates.\n\u003e - Use these skills for exploration, onboarding, gap analysis, and architectural conversations — not for automated quality enforcement.\n\n### What to do if you need determinism\n\nDon't invoke skills in CI. Pair them with deterministic tools instead:\n\n1. Invoke the skill **once** locally to get a review.\n2. 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).\n3. Use the **script** in CI. The script is deterministic. The skill is exploratory.\n\n| Use case | What to use |\n|---|---|\n| Exploration, onboarding, gap analysis, architecture conversations | Skill |\n| Pre-merge gate, CI, compliance audit | Generated script (with tools the skill picked for your stack) |\n| Continuous dashboard | Skill output to seed the dashboard; scripts to keep it updated |\n\nSkills 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.\n\n- **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.\n- **Hybrid**: some aspects deterministic, others LLM judgment. Use the script in CI for the deterministic part; keep invoking the skill for the rest.\n- **LLM-pure**: no deterministic counterpart exists; non-determinism is the feature. Don't try to put this in CI — its value is the conversation.\n\n| Skill | Category | Deterministic counterpart |\n|---|---|---|\n| `assess-iac` | tool-backed | Checkov + Trivy + tfsec scan workflow |\n| `assess-configuration` | tool-backed | Schema validation + secret-detection script |\n| `assess-secure-coding` | hybrid | `security-scan.sh` (semgrep / bandit / gosec / etc.) |\n| `assess-testing` | hybrid | CI workflow with coverage thresholds + flake detection |\n| `assess-observability` | hybrid | CI check that flags handlers without instrumentation |\n| `assess-data-design` | hybrid | SQL/schema lint + slow-query (EXPLAIN) regression check |\n| `assess-ci-cd` | hybrid | Pipeline-files lint workflow |\n| `assess-contract-design` | hybrid | Spectral / buf / graphql-eslint validation in CI |\n| `assess-coding-principles` | LLM-pure | Complexity report (partial — flags structural smells only) |\n| `assess-system-design` | LLM-pure | Fitness functions (architecture tests) — see [`well-architected/fitness-functions.md`](well-architected/fitness-functions.md) |\n\nThe deterministic counterpart for each skill is the **first** offer in that skill's `What I Can Generate` section.\n\n---\n\n## How the Domains Relate\n\n```\nbackend-engineering/     ← canonical base (all other domains reference this)\n  ├── frontend-engineering/   references backend + adds frontend-specific (XSS, RUM, SPA/SSR, components)\n  ├── data-engineering/       references backend + adds data-specific (pipelines, quality, dimensional modeling)\n  ├── ai-engineering/         references backend + adds AI-specific (prompts, RAG, agents, eval, guardrails)\n  └── ml-engineering/         references backend + adds ML-specific (training, MLOps) [pending]\n```\n\nContent that's identical across domains lives in `backend-engineering/` only. Other domains:\n- Reference backend for shared content (software principles, CI/CD, IaC, data privacy)\n- Create domain-specific files where practices differ\n- Don't include topics that don't apply (frontend has no data-design, for example)\n\n---\n\n## How to Use This Repo\n\n### As a developer (human)\n1. Start with your domain (`backend-engineering/`, `frontend-engineering/`, etc.)\n2. Each domain has a README that maps topics → files\n3. Each file is self-contained with principles, anti-patterns, and tooling\n4. Cross-references point to related content (never required — each file stands alone)\n\n### As an AI coding assistant\n1. Read the relevant domain README to understand structure\n2. Read specific topic files based on the review/task at hand\n3. Skills in `.skills/` are pre-built prompts that automate this (domain detection + appropriate file reading)\n4. Cross-cutting frameworks (`zero-trust/`, `well-architected/`) provide lens for architectural review\n\n### Installing skills in your project\n```bash\n# Clone this repo\ngit clone https://github.com/guidomantilla/best-practices.git\n\n# Install skills into your project (choose your tool)\nmake install-claude TARGET=~/projects/my-app        # Claude Code\nmake install-copilot TARGET=~/projects/my-app       # GitHub Copilot\nmake install-cursor TARGET=~/projects/my-app        # Cursor\n\n# Install only specific skills\nmake install-claude TARGET=~/projects/my-app SKILLS='assess-secure-coding assess-testing'\n\n# Roll back an install\nmake uninstall-claude TARGET=~/projects/my-app\nmake uninstall-all TARGET=~/projects/my-app          # all 3 tools at once\n\n# List available skills\nmake list\n```\n\n### Quick start (after installing)\n\nAfter `make install-claude`, open Claude Code in your project and try:\n\n**1. Discover what's installed**\n```\n/best-practices\n```\nor, in natural language:\n```\nwhat best-practices skills do I have here?\n```\nClaude responds with a catalog of the 10 assessment skills, what each one covers, and when to use it.\n\n**2. Run a focused assessment**\n```\n/assess-secure-coding src/api/\n```\nClaude 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.\n\n**3. Ask in natural language**\n```\nreview the testing strategy for this service — are there gaps?\n```\nClaude auto-invokes `assess-testing`, walks the test pyramid, flags missing levels, and proposes the highest-value tests to add first.\n\nIn Cursor and Copilot, the same content is loaded as rules / instructions — invoke by asking the assistant directly (slash commands are Claude-Code-specific).\n\n### For a new project\n1. Install skills (see above)\n2. `backend-engineering/system-design/methodology.md` — ADRs, trade-off analysis, quality attribute scenarios\n3. `well-architected/` — the 5 pillars checklist\n4. `zero-trust/` — security posture from day 1\n5. Your domain folder — domain-specific best practices\n\n---\n\n## Design Decisions\n\n| Decision | Rationale |\n|---|---|\n| **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. |\n| **Backend is canonical** | Backend is the foundation of all software. Frontend, data, and AI extend it — they don't exist without it. |\n| **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. |\n| **Each file is self-contained** | You can read one file and get value. Cross-references are \"for more depth\", never \"go read this instead\". |\n| **Anti-patterns alongside practices** | Knowing what NOT to do is as valuable as knowing what to do. Every section has anti-patterns. |\n| **Tooling is examples, not prescriptions** | Tools change faster than principles. Mentioned as examples, not mandates. |\n| **Skills use relative paths** | Portable — works for anyone who clones the repo, regardless of where they put it. |\n| **No sustainability pillar** | AWS-only concept, out of scope for this repo. |\n| **No mobile/platform engineering** | Mobile is a different world (not the author's domain). Platform engineering is operations, not code best practices. |\n| **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. |\n\n---\n\n## References (Foundational)\n\n### Standards \u0026 Frameworks\n- [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/)\n- [CWE Top 25](https://cwe.mitre.org/top25/)\n- [NIST SP 800-207 — Zero Trust Architecture](https://csrc.nist.gov/pubs/sp/800/207/final)\n- [CISA Zero Trust Maturity Model v2](https://www.cisa.gov/resources-tools/resources/zero-trust-maturity-model)\n- [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)\n\n### Books\n- Bass, Clements, Kazman — *Software Architecture in Practice* (4th ed, 2021)\n- Richards, Ford — *Fundamentals of Software Architecture* (2nd ed, 2024)\n- Kleppmann — *Designing Data-Intensive Applications* (2017)\n- Hohpe, Woolf — *Enterprise Integration Patterns* (2003)\n- Chip Huyen — *AI Engineering* (2025)\n- Kimball — *The Data Warehouse Toolkit* (2013)\n- Martin — *Clean Code* (2008) · *Clean Architecture* (2017)\n- Beck — *Test-Driven Development* (2003)\n- Gamma et al. — *Design Patterns* (1994)\n- Hunt, Thomas — *The Pragmatic Programmer* (1999)\n\n---\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE).\n\nCopyright 2026 Guido Mauricio Mantilla Tarazona (guidomau / usq0x6e.co). Bogotá, Colombia.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguidomantilla%2Fbest-practices","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguidomantilla%2Fbest-practices","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguidomantilla%2Fbest-practices/lists"}