General (Cross-Framework) Coding Standard (v1.0)

Status: Locked v1.0. Language-agnostic baseline applied to every project. The framework standards (python, nodejs, go, …) layer on top with stack-specific rules; on overlap the stricter rule wins. custom-standards overrides this document on conflict. Same RFC-2119 constraint language, GEN-AREA-N rule IDs, and severity mapping as the framework standards.

How to read this document

Constraint language (RFC 2119)

• MUST / MUST NOT — hard requirement; a violation is a blocking issue.
• SHOULD / SHOULD NOT — strong recommendation; deviate only with a written justification.
• MAY — optional.

Rule IDs

Stable GEN-AREA-NUMBER (e.g. GEN-SEC-3). The reviewer MUST cite the rule ID. Never renumber.

Severity mapping

1. Version Control & Commits

• GEN-VCS-1 (MUST): Make small, focused commits with imperative-mood subject lines (≤ ~72 chars) describing why, not just what. MUST NOT mix unrelated changes in one commit.
• GEN-VCS-2 (MUST NOT): Commit secrets, credentials, .env files, or large binaries. Use a .gitignore and a secret manager. A committed secret is a blocking, drop-everything issue.
• GEN-VCS-3 (SHOULD): Keep the default branch releasable. Develop on feature branches; open PRs with a description of intent, scope, and test evidence.
• GEN-VCS-4 (SHOULD): Don't commit commented-out code or dead code "just in case" — version control already remembers it.

2. Documentation

• GEN-DOC-1 (SHOULD): Every repository has a README covering what it is, how to set it up, how to run it, and how to test it.
• GEN-DOC-2 (SHOULD): Document the why in code comments (intent, trade-offs, non-obvious constraints) — not the what the code already says. Delete stale comments.
• GEN-DOC-3 (SHOULD): Public APIs/modules carry doc comments in the language's convention (docstrings, JSDoc/TSDoc, godoc, Javadoc, rustdoc). Keep them in sync with the code.
• GEN-DOC-4 (MAY): Record significant architectural decisions (an ADR or a short note) so the reasoning survives turnover.

3. Testing Philosophy

• GEN-TEST-1 (MUST): New or changed behavior ships with tests. The reviewer/QA agent treats changed logic with no corresponding test as insufficient coverage.
• GEN-TEST-2 (MUST): Target ≥ 80% coverage on changed code (not whole-repo). Coverage is a floor, not the goal — don't chase it on trivial code, and flag tests with no assertions or only truthiness checks as inadequate.
• GEN-TEST-3 (SHOULD): Follow the test pyramid — many fast unit tests, fewer integration, few end-to-end. Tests are deterministic and isolated: no real external network in unit tests, no order dependency, no shared mutable state.
• GEN-TEST-4 (SHOULD): Name tests by behavior, follow Arrange–Act–Assert, and cover the failure/authorization-rejection paths, not just the happy path. A test that reveals a real defect is reported — never silenced by changing source to make it green.

4. Security Baseline

• GEN-SEC-1 (MUST NOT): Hard-code secrets, API keys, tokens, or credentials. Load them from the environment or a secret manager.
• GEN-SEC-2 (MUST): Validate and treat all external input as untrusted — request bodies, query params, headers, file contents, env. Reject malformed input at the boundary.
• GEN-SEC-3 (MUST NOT): Build queries (SQL/NoSQL/shell) by string concatenation. Use parameterized queries / safe APIs to prevent injection.
• GEN-SEC-4 (MUST): Never log secrets, tokens, or PII. Apply least privilege to credentials and tool/file permissions.
• GEN-SEC-5 (SHOULD): Keep dependencies patched and scanned (the stack's audit tool — pip-audit, npm audit, govulncheck, OWASP Dependency-Check, cargo audit). Vet new dependencies — every one is supply-chain surface.
• GEN-SEC-6 (SHOULD): Cover the OWASP Top 10 classes relevant to the stack: broken access control, injection, auth failures, security misconfiguration, vulnerable components, SSRF.

5. Code Quality & Architecture

• GEN-ARCH-1 (SHOULD): Keep separation of concerns — distinct layers/modules for transport, business logic, and data access. Don't leak transport types into the domain or SQL into handlers.
• GEN-ARCH-2 (MUST NOT): Introduce circular dependencies between modules/packages.
• GEN-ARCH-3 (SHOULD): Favor low coupling / high cohesion; depend on abstractions at module boundaries. Dependencies flow inward (toward the domain), not outward.
• GEN-ARCH-4 (SHOULD): Apply DRY and SOLID judiciously — eliminate true duplication, but don't over-abstract speculative cases. Prefer the simplest design that is sound.
• GEN-ARCH-5 (SHOULD): Keep functions/units small and single-purpose; cap cyclomatic complexity (~10) and keep the happy path shallow with early returns.
• GEN-ARCH-6 (SHOULD): Apply consistent patterns across the codebase — a reviewer flags the same concern solved three different ways as an inconsistency smell.

6. Observability & Errors

• GEN-OBS-1 (MUST): Use the stack's structured logger, not print/console.log/println, for application logging in production code paths.
• GEN-OBS-2 (SHOULD): Handle errors deliberately — don't swallow them; add context as they cross layers; log an error once, where it's handled. Surface a safe message to users; never leak stack traces or internals.
• GEN-OBS-3 (SHOULD): Emit a correlation/request ID and expose health/readiness for services.