03 — Architecture and Code Quality Checklist#

Review design trade-offs, system boundaries, maintainable code, engineering reviews, decision records, and API/frontend architecture. This checklist evaluates structure and evolvability; it complements the dedicated Testing, Security, DevOps, and Performance files.

Scope: Shared / cross-cutting. This file is one part of the 03_Architecture_and_CodeQuality.md checklist. Apply the domain-wide release gate across all applicable scope files; each checklist ID remains unique.

Review details#

• Project / product:
• Release / version / environment:
• Scope and applicable jurisdictions / markets:
• Reviewer / owner:
• Review date:
• Decision: Pending / Approved / Approved with documented exceptions / Blocked

How to use#

1. Copy this reusable checklist into a project-specific review; leave all boxes unchecked in this shared repository.
2. Mark [x] only after confirming an item through source review, current diagrams, ADRs, build rules, interface contracts, or other evidence. Record failed checks and documented N/A decisions separately in project review notes or issues using their ARC IDs.
3. Prioritize consequential design choices and maintainability risks. A modular monolith, services, or another pattern may all be appropriate depending on the project; no specific architecture is universally required.
4. Check ## API Checks and ## Frontend Checks independently where applicable. Refer detailed functional testing, security vulnerabilities, accessibility conformance, and performance validation to their corresponding checklists.
5. Reassess when major dependencies, product boundaries, public contracts, staffing, or architectural assumptions change.

Architecture and system boundaries#

• ARC-002 Choose an architecture style based on actual domain complexity, scale, team capabilities, and non-functional requirements; record its alternatives and trade-offs.
• ARC-003 Identify bounded contexts, business capabilities, and ownership for each major service or module.
• ARC-004 Define clear component responsibilities so domain rules are not duplicated across unrelated layers.
• ARC-005 Make dependency directions explicit and prevent accidental cycles between modules or services.
• ARC-006 Check that component boundaries promote high cohesion and loose coupling rather than arbitrary microservice fragmentation.
• ARC-007 Document public and internal interfaces, events, queues, storage boundaries, and integration owners.
• ARC-008 Clarify which component owns each persistent data entity and who can modify its canonical state.
• ARC-009 Review whether synchronous calls and distributed transactions are necessary, and account for latency or partial failures across boundaries.
• ARC-010 Specify event delivery, ordering, duplication, and eventual-consistency assumptions for asynchronous communication when used.
• ARC-011 Identify single points of failure and the architectural recovery or degradation strategies for critical user workflows.
• ARC-013 Assess whether third-party products, managed services, or custom implementations reduce or increase complexity and operational burden.
• ARC-014 Verify the architecture supports documented performance, availability, privacy, accessibility, and cost constraints without overengineering.
• ARC-016 Limit unnecessary sharing of databases, mutable state, build artifacts, and privileged credentials between unrelated components.
• ARC-017 Ensure architectural diagrams reflect the current implementation, not only an obsolete initial proposal.
• ARC-018 Assign a technical owner to each critical component and dependency and document the escalation path for design changes.

Code organization and maintainability#

• ARC-019 Group related functionality into coherent modules or packages with clear names and public interfaces.
• ARC-020 Keep business logic separate from transport, persistence, framework glue, and presentation where this reduces coupling.
• ARC-021 Ensure implementations expose only the minimum intended public surface; hide internal helpers and representation details.
• ARC-022 Use language-appropriate naming, formatting, linting, and typing conventions consistently across the repository.
• ARC-023 Keep functions, classes, and components focused enough for a reviewer to understand their responsibilities.
• ARC-024 Replace unnecessary duplication with reusable abstractions only when they clarify actual repeated behavior.
• ARC-025 Avoid speculative generalization, unused extension points, and abstractions that add more complexity than they remove.
• ARC-026 Make exceptional behavior explicit using appropriate error types, return contracts, and structured recovery paths.
• ARC-027 Document non-obvious invariants, concurrency assumptions, and why unusual code exists rather than narrating obvious syntax.
• ARC-028 Check that configuration and environment-dependent behavior are separated from application logic and have safe defaults.
• ARC-029 Make dependency injection and seams for external integrations practical enough for isolated testing.
• ARC-030 Use immutable values or controlled state updates when they simplify reasoning about concurrent or asynchronous code.
• ARC-032 Ensure new dependencies have a documented need, maintained version policy, and no unnecessary duplication of existing capabilities.
• ARC-033 Provide concise development and build instructions so a new maintainer can locate entry points and reproduce a build.
• ARC-034 Keep generated code, migrations, and build artifacts clearly distinguished from manually maintained source.
• ARC-035 Use tooling or targeted refactoring to prevent unbounded module size, circular imports, and hidden coupling over time.

Reviews and technical debt#

• ARC-036 Require an appropriate peer review or approved alternative for meaningful code changes, with high-risk changes receiving suitable specialist review.
• ARC-037 Keep change sets small and self-contained where practical, including related tests and documentation.
• ARC-038 Write change descriptions that explain what changed, why, user impact, and relevant migration or compatibility considerations.
• ARC-039 Have reviewers examine overall design fit before focusing on line-level style concerns.
• ARC-040 Review for correctness, readability, naming, unnecessary complexity, and conformity with established conventions.
• ARC-041 Review concurrency, error paths, lifecycle/resource cleanup, and side effects where applicable.
• ARC-042 Evaluate whether tests meaningfully cover the changed behavior; refer detailed test adequacy to the Testing checklist.
• ARC-044 Record substantial reviewer disagreements, the resolution, and accountable decision-maker.
• ARC-045 Track recurring defects or friction that indicate structural debt rather than applying only local patches.
• ARC-046 Maintain a prioritized technical-debt backlog with impact, owner, mitigation, and expected remediation window.
• ARC-047 Distinguish intentional short-term compromises from unnoticed complexity and preserve their rationale.
• ARC-048 Identify high-change or high-defect modules and consider targeted decomposition or refactoring with measurable outcomes.
• ARC-049 Ensure required changes to public contracts, dependency owners, and operational runbooks are captured in the same review cycle.
• ARC-050 Confirm accepted review suggestions are applied or explicitly resolved before approval.
• ARC-051 Review whether a change improves or degrades overall code health, not just whether its immediate feature works.

Architecture decisions and evolution#

• ARC-052 Use an architecture decision record (ADR) or equivalent for material structural, technology, interface, and operational choices.
• ARC-053 Capture the decision context, constraints, alternatives considered, chosen option, and expected consequences.
• ARC-054 Record each material decision's status, date, owner, and affected components.
• ARC-055 Make significant architectural assumptions and trade-offs discoverable to future maintainers.
• ARC-056 Keep superseded decisions in history and link the replacement rather than silently rewriting past rationale.
• ARC-057 Review architecture against observed change frequency, outages, cost, and developer feedback at an agreed cadence.
• ARC-058 Define objective architecture fitness checks such as dependency-rule checks, contract checks, or measured performance constraints where appropriate.
• ARC-059 Plan versioned interfaces and incremental migrations to reduce simultaneous changes across dependent components.
• ARC-061 Document whether new components can be rolled back or replaced independently and the constraints on doing so.
• ARC-062 Periodically reconsider if the selected architecture remains the simplest adequate approach for the current scale and team.
• ARC-063 Retire unused modules, obsolete integrations, abandoned flags, and deprecated pathways through planned cleanup.
• ARC-064 Link architecture follow-ups to owners, milestones, and observable completion criteria rather than leaving undocumented intentions.

Release gate#

• Critical component boundaries, data ownership, public interfaces, and major failure/dependency paths are understood and reviewed by accountable engineers.
• Material architectural decisions are recorded, including alternatives, trade-offs, owners, and any unresolved risks.
• Changes affecting critical APIs or frontend architecture have documented compatibility and migration implications, with an approved path for affected consumers.
• The proposed code and structure have received the required engineering review, and no unresolved high-impact maintainability or design defect remains without documented acceptance by an authorized owner.
• All open architecture/code-quality blockers have named owners, dispositions, and follow-up dates in project-specific records.

Domain-specific approval rule: Block architecture approval for unowned critical interfaces or data, undocumented breaking changes, structural defects likely to invalidate core system guarantees, or unaccepted high-impact maintainability risks. Passing this review does not establish that functional, security, or operational testing has succeeded.

Trusted references and scope#

These checks interpret selected guidance into practical review questions; they are not direct quotations or a certification against any one framework.

• Microsoft Azure Architecture Center — Architecture styles — choosing styles with explicit trade-offs and domain fit.
• Microsoft Azure Architecture Center — Design for evolution — high cohesion, loose coupling, contracts, domain ownership, and controlled change.
• AWS Well-Architected Framework — Operational excellence design principles — small reversible changes, failure anticipation, and iterative operational improvement.
• AWS Prescriptive Guidance — Architectural decision records — documenting and communicating important architectural decisions.
• AWS Prescriptive Guidance — ADR best practices — ownership, status, review cadence, and preserved decision history.
• Google Engineering Practices — What to look for in a code review — readability, complexity, design, correctness, and code health.
• Google Engineering Practices — Small changes — focused, reviewable, reversible changes.
• OpenAPI Specification 3.2.1 — machine-readable HTTP API contracts when applicable.
• web.dev — Rendering on the web — selecting frontend rendering approaches according to their trade-offs.
• web.dev — Code-split JavaScript — modular JavaScript loading and startup responsiveness.

Applicability: Adapt check granularity to the project's size, language, architecture style, team, and risk. Independent deployment, event messaging, OpenAPI, and browser rendering are conditional—not mandatory for every project. Prefer simple designs that satisfy measured requirements.

Source review date: 2026-11-12.

Suggested testing tools#

Choose tools appropriate to the project's stack and risks; automation supports evidence but does not approve the checklist.

• Test focus: dependency boundaries, code quality, interface contracts, and architectural regression; include shared/cross-team controls where applicable.
• Cross-stack: Semgrep + dependency-cruiser.
• Python: Ruff + mypy + pytest; for pytest-based suites, run python -m pytest -q.
• TypeScript: TypeScript tsc + ESLint + Vitest; for Vitest-based suites, run npx vitest run (or npx playwright test for E2E).
• JavaScript: ESLint + Jest; for Jest-based suites, run npx jest --ci (or npx playwright test for E2E).
• Evidence: Save tool versions, configuration, test environment, fixtures, results, and links in project-specific review records using the existing checklist IDs. Expert review remains necessary where relevant.

Suggested AI skills for verification#

These are optional agent review aids, not automated passes or release approval. Each linked repository had at least 1,000 GitHub stars when checked on 2026-11-12; counts are per repository, not per skill, and do not indicate security or correctness.

• improve-codebase-architecture — Review modules, boundaries, and coupling (mattpocock/skills, 322,608 repo stars).
• code-review-and-quality — Inspect maintainability and correctness risks (addyosmani/agent-skills, 116,378 repo stars).
• architecture-patterns — Check architecture and integration decisions (wshobson/agents, 42,437 repo stars).

How to check: In a project-specific copy, have the agent audit the shared / cross-cutting scope and map findings to this file's existing checklist IDs, with code/configuration references, reproducible test results, failed or inapplicable cases, and uncertainties. Independently verify findings; keep shared template boxes unchecked and retain human approval requirements.

Before use: Read the skill's SKILL.md, referenced scripts, license, and requested tool permissions. Only execute vetted skills with appropriate access in a controlled environment.

Important warning: reference only#

⚠️ Reference only — not a definitive or exhaustive checklist. This template is a starting point for review, not the ultimate authority or a guarantee of project safety, quality, regulatory compliance, accessibility, security, or launch readiness.

Use project-specific judgment and independent verification. Requirements and risks evolve and differ by project, technology, and jurisdiction. Adapt the checks, consult current authoritative sources, perform relevant tests, and obtain qualified specialist review or approval when appropriate. Checking every box does not replace these steps.