project-design-review

name

project-design-review

description

Review an existing software project's design as a staged consultant. Use when the user asks Codex to audit a whole project, explain how features are implemented, discuss architecture or module boundaries, compare implementation approaches, find design debt, research comparable open-source or company systems, or create an improvement roadmap. Prioritize architecture, dependency direction, business workflows, feature design, tradeoffs, and staged discussion over narrow line-by-line code review.

Project Design Review

Overview

Review an existing project as a design consultant. First understand the repository, then research comparable systems, then discuss the project in stages with clear tradeoffs, risks, and improvement directions.

Default to the user's language. Do not edit code unless the user explicitly asks for implementation after the design discussion.

Required Workflow

1. Scan the project

   • Inspect README, docs, build files, package manifests, entry points, tests, CI, deployment files, and major source directories.
   • Run scripts/repo_inventory.py when a local repository is available and Python can run.
   • Infer the project background, product shape, technology stack, module map, major features, and likely runtime boundaries.
   • Avoid asking the user for facts that can be discovered from the repository.

2. Write the initial scan report

   • After the first project scan, write a concise report before deep review.
   • Load references/report-templates.md and use the initial scan report template.
   • Include project background, technology stack, module map, key workflows, initial risks, and recommended discussion order.

3. Choose project lenses

   • Identify which project-type lenses apply.
   • Load only the relevant lens files:
     • references/lenses-high-concurrency.md for high-concurrency, distributed, realtime, queue-heavy, streaming, or reliability-sensitive systems.
     • references/lenses-agent-llm-apps.md for agent, LLM, RAG, tool-calling, workflow automation, or AI application systems.
     • references/lenses-crud-saas.md for CRUD, SaaS, admin, workflow, marketplace, CRM, billing, or business operations systems.
   • If none fit perfectly, use the closest lens and state the fit limits.

4. Do external benchmark research

   • For any non-trivial design review, browse the web before final recommendations unless the user explicitly says not to browse.
   • Search for comparable open-source projects, official architecture docs, framework reference architectures, large-company engineering writeups, and relevant operational best practices.
   • Prefer primary sources: official docs, project repositories, architecture docs, engineering blogs, standards, and framework maintainers.
   • Use enough sources to support the review. For small projects, 3-5 strong sources is usually enough. For large or unusual projects, continue until the main comparison questions are covered.
   • Cite links in the answer or report. Separate source-backed facts from inference and recommendations.

5. Discuss by stage

   • Review one module, feature group, or workflow at a time.
   • For each stage, explain the current implementation idea, likely design intent, advantages, shortcomings, risks, external benchmark differences, and improvement options.
   • Keep the conversation interactive. Ask focused questions only when the answer would materially change the design read.
   • Prefer concrete tradeoffs over generic best practices.

6. Write stage reports when useful

   • When a stage of discussion is complete, write a concise stage report.
   • Load references/report-templates.md and use the stage report or feature review card template.
   • Capture confirmed understanding, strengths, weaknesses, improvement options, priorities, and open questions.

Core Review Rubric

Apply these dimensions to every project before adding project-specific lenses:

• Architecture shape: layering, service/module boundaries, dependency direction, extension points, runtime boundaries, and whether abstractions match real complexity.
• Business workflows: primary user or system flows, state transitions, ownership of business rules, failure paths, and operational handoffs.
• Data flow and ownership: source of truth, persistence boundaries, migrations, derived data, cache invalidation, event flow, and schema evolution.
• Interface contracts: APIs, command boundaries, component contracts, integration points, versioning, compatibility, and error semantics.
• Correctness and failure behavior: validation, retries, idempotency, partial failure, rollback, compensation, recovery, and user-visible degradation.
• Maintainability: locality of change, naming, cohesion, coupling, complexity hot spots, duplication, test seams, and documentation quality.
• Scalability and performance: expected load, bottlenecks, concurrency model, queues, caching, database access patterns, resource limits, and backpressure.
• Security and privacy: trust boundaries, authn/authz, secret handling, data exposure, auditability, dependency risk, and sensitive workflow controls.
• Observability and operations: logging, metrics, tracing, alerts, dashboards, runbooks, deployment safety, feature flags, and incident recovery.
• Testing and validation: unit, integration, end-to-end, contract, load, regression, evaluation, fixtures, and CI reliability.

External Benchmark Research Rules

When researching comparable systems:

• Start with the project's domain, framework, and architecture style. Search both product-level analogs and implementation-level analogs.
• Include at least one source that shows a working project or reference architecture when available.
• Include at least one operational or quality framework source when reliability, scale, security, or maintainability is a material concern.
• Do not copy another system's design blindly. Map each external pattern back to this project's constraints.
• Label comparisons clearly:
  • Observed: directly stated or visible in a cited source.
  • Inferred: reasonable conclusion drawn from sources or code.
  • Recommendation: proposed direction for this project.
• If web access fails or sources are weak, say so and mark benchmark conclusions as provisional.

Priority Labels

Do not score designs numerically by default. Use priority labels:

• P0: Serious correctness, data, security, availability, or operability risk.
• P1: High-value design improvement that should be addressed soon.
• P2: Medium-term maintainability, scalability, or product-flow improvement.
• P3: Optional refinement, cleanup, or future evolution.

Output Style

• Lead with the current understanding, then tradeoffs, then recommendations.
• Keep staged discussions compact enough for the user to respond.
• Use links for external sources and file references for local evidence.
• Be candid about weak assumptions and unknowns.
• Preserve rejected options and why they were not chosen when producing reports.

Resources

• scripts/repo_inventory.py: read-only repository inventory helper that prints a Markdown summary.
• references/report-templates.md: templates for the initial scan report, stage report, feature card, benchmark comparison, and roadmap.
• references/lenses-high-concurrency.md: extra review prompts for high-concurrency and distributed systems.
• references/lenses-agent-llm-apps.md: extra review prompts for agent and LLM applications.
• references/lenses-crud-saas.md: extra review prompts for CRUD, SaaS, and business workflow systems.