> ## Documentation Index > Fetch the complete documentation index at: https://hedgeem-api.qeetoto.com/llms.txt > Use this file to discover all available pages before exploring further. # Productionize This Codebase > A reusable Claude Code skill (/productionize) that runs a deep, autonomous non-functional-requirements review before shipping a vibe-coded app to production. Deep, autonomous non-functional-requirements (NFR) review of a vibe-coded, functionally-complete app — surfaces production-readiness gaps (performance, efficiency, security, capacity, extensibility, rate limiting in and out of the app, and anything else a real production deployment needs) and hands back a findings + action list + phased remediation plan. This skill is **read-only** by design — it never edits application code. It only ever produces documentation for a human to act on separately. This page documents the `/productionize` Claude Code skill, installed globally at `~/.claude/commands/productionize.md` so it's available from any project, not just this one. ## Usage ``` /productionize /productionize focus heavily on outbound rate limiting — we're getting 429s from a third-party API and I think our retry/backoff design is wrong /productionize docs/productionization/rate-limit-focus.md ``` * **No argument** → comprehensive sweep across every default category below, no special emphasis. * **Argument that resolves to an existing file** (relative to the repo root, or absolute) → read that file in full as this run's detailed customization instructions. Treat its contents as **additive** to the default category list (it narrows/emphasizes, it doesn't silently drop categories) unless the file explicitly says to skip something. * **Argument that is not a valid file path** → treat it as inline free-text focus/emphasis for this run, layered on top of the default full sweep the same way. ## Step 0 — Resolve this run's focus 1. Work out which of the three argument modes above applies. 2. Derive a short kebab-case slug from the focus for filenames (e.g. `outbound-rate-limiting`, `full-sweep` if no argument was given). 3. Note today's date (`date +%Y-%m-%d`). ## Step 1 — Ground yourself in the real codebase first Do this before writing anything — don't hand a blind brief to the investigating agent. Use Explore agents for a large/unfamiliar codebase; read key files directly for a small one. At minimum, establish: * Language(s), framework(s), how it's built/run/deployed (`package.json`/equivalent scripts, Dockerfile, CI config, IaC, hosting platform). * What NFR-relevant mechanisms already exist: rate limiting or throttling (inbound and outbound), retry/backoff logic, circuit breakers, caching, connection pooling/limits, timeouts, logging/observability, secrets management, authn/authz, error handling patterns, existing test coverage, CI/CD gates. * Every third-party API/service the app calls — especially load-bearing if this run is about outbound rate limiting: enumerate them, any documented rate limits you can find in code/config/comments/vendor docs, and exactly how the app currently reacts to 429s/backpressure/timeouts from each (retries? backoff? queuing? nothing at all?). * Whether any existing project docs (README, CLAUDE.md, architecture notes) describing current NFR posture are trustworthy — verify against actual code rather than assuming they're current; call out anything stale. ## Step 2 — Write a self-contained, repo-grounded brief Write it to `docs/productionization/--BRIEF.md` (create the directory if needed). It must stand alone — the agent executing it in Step 3 has no memory of this conversation. Include: * **Mission** — the investigating agent acts as a multi-disciplinary production-readiness review team (performance engineer, security engineer, SRE/capacity planner, API-integration architect, technical writer) auditing this specific codebase — not a generic checklist exercise. * **Grounding section** — every verified fact from Step 1 (stack, deployment target, what NFR mechanisms already exist, the third-party dependency inventory, any stale-doc warnings), phrased as verified facts, so the agent starts from reality instead of re-deriving it or guessing. * **Review categories** — always in scope unless this run's focus explicitly narrows them out (state clearly whether this run narrows scope to one category or just weights it more heavily within a full sweep): * Performance * Efficiency (compute/memory/cost, not just latency) * Security * Capacity (what load does this actually fall over at, and where's the ceiling) * Extensibility (how much pain does the next feature/integration cost, architecturally) * Rate limiting — **inbound**: is this app's own surface (API routes, webhooks, public endpoints) protected against abuse/overload? * Rate limiting — **outbound**: for every third-party API/service the app depends on, is there real backoff/retry/concurrency-control/circuit-breaking, or does it just hammer the API and hope? * Other NFRs the agent should proactively identify and is expected to go looking for even though they're not enumerated above — explicitly prompt for: observability/monitoring/alerting, resilience & error handling, logging & audit trails, secrets/credentials management, backup & disaster recovery, dependency/supply-chain health, cost efficiency, compliance considerations (if applicable to the domain), deployment & rollback safety, operational runbooks/documentation, test coverage & CI/CD gates. * **This run's focus** — the resolved emphasis/narrowing from Step 0, stated explicitly. * **Working method**: * **Read-only.** Never edit application code, never run destructive or state-changing commands, never commit, stage, or push anything. * Verify claims empirically wherever you safely can without modifying anything — run the app locally, exercise real endpoints, read actual response headers/timings/logs, run the *existing* test suite — but do not add, change, or commit code to do so. * Work autonomously without pausing to ask questions. If something is genuinely ambiguous or needs a business/human judgment call (budget, risk appetite, compliance posture), record it as an open question in the report rather than stopping. * There is no time limit — investigate as long as it takes to be thorough. Depth over speed. * **Required report structure** (so every run is consistent and comparable over time) — write the final report to `docs/productionization/--REPORT.md`: 1. **Executive summary** — a few sentences: overall production-readiness verdict, top 3–5 risks. 2. **Findings**, grouped by category. Each finding needs: severity (Critical/High/Medium/Low), one-line summary, concrete evidence (real `file:line` references — no vague claims), a concrete failure scenario (what breaks, under what real-world condition), and a recommended action. 3. **Tangible action list** — a flat, prioritized checklist derived straight from the findings, usable directly as a backlog. 4. **Phased remediation plan** — group actions into phases (e.g. "before any real traffic", "before scaling up", "nice to have"), noting rough effort and any dependencies between phases. 5. **Open questions** — anything needing a human/business decision rather than a pure engineering call. ## Step 3 — Launch the investigation 1. Determine the model: default to `fable`. If the resolved focus (inline text or customization file) explicitly requests a different model (e.g. "model:sonnet", "use opus"), honor that instead. 2. Launch via the Agent tool with that model, `run_in_background: true`, instructing it to read the brief file in full and execute it exactly, writing its report to the path specified in the brief. 3. Do not poll or wait. Tell the user the investigation has been launched, where the brief lives, and that results will be relayed when it completes. ## Step 4 — When it reports back * Read the produced report and spot-check a handful of its `file:line` claims against the real repo before relaying anything — don't take it on faith. * Give a concise summary: top findings by severity, the prioritized action list, where the full report and plan live. Don't dump the entire report inline. * Do not implement anything from the findings automatically — this skill's job ends at the report. Acting on it is a separate, explicit follow-up. ## Notes * This skill produces documentation only, on purpose — it's meant to run repeatedly over a project's life with different focuses (e.g. first an outbound-rate-limiting-specific run, later a full sweep, later a security-specific pass), and `docs/productionization/` becomes a running, dated audit trail. Runs are not collapsed into one file. * The brief this skill writes should read like a grounded engineering document, not a generic checklist: every claim in it should be something actually verified in Step 1, not boilerplate. That rigor is the entire point — it's what lets the investigating agent spend its time finding real problems instead of re-discovering facts about the repo it's sitting in. * Deliberately does not `git add`/`commit`/`push` anything, including its own brief/report files — they're left as new, uncommitted files for a human to review and commit once read. ## Installing on another machine ```bash theme={null} mkdir -p ~/.claude/commands ``` Copy the block below verbatim into `~/.claude/commands/productionize.md` on the target machine. ````markdown theme={null} # Productionize This Codebase Deep, autonomous non-functional-requirements (NFR) review of a vibe-coded, functionally-complete app — surfaces production-readiness gaps (performance, efficiency, security, capacity, extensibility, rate limiting in and out of the app, and anything else a real production deployment needs) and hands back a findings + action list + phased remediation plan. **Read-only**: this skill never edits application code — it only ever produces documentation for you to act on separately. ## Usage ``` /productionize /productionize focus heavily on outbound rate limiting — we're getting 429s from a third-party API and I think our retry/backoff design is wrong /productionize docs/productionization/rate-limit-focus.md ``` - **No argument** → comprehensive sweep across every default category below, no special emphasis. - **Argument that resolves to an existing file** (relative to the repo root, or absolute) → read that file in full as this run's detailed customization instructions. Treat its contents as **additive** to the default category list (it narrows/emphasizes, it doesn't silently drop categories) unless the file explicitly says to skip something. - **Argument that is not a valid file path** → treat it as inline free-text focus/emphasis for this run, layered on top of the default full sweep the same way. ## Step 0 — Resolve this run's focus 1. Work out which of the three argument modes above applies. 2. Derive a short kebab-case slug from the focus for filenames (e.g. `outbound-rate-limiting`, `full-sweep` if no argument was given). 3. Note today's date (`date +%Y-%m-%d`). ## Step 1 — Ground yourself in the real codebase first Do this yourself before writing anything — don't hand a blind brief to the investigating agent. Use Explore agents for a large/unfamiliar codebase; read key files directly for a small one. At minimum, establish: - Language(s), framework(s), how it's built/run/deployed (`package.json`/equivalent scripts, Dockerfile, CI config, IaC, hosting platform). - What NFR-relevant mechanisms already exist: rate limiting or throttling (inbound and outbound), retry/backoff logic, circuit breakers, caching, connection pooling/limits, timeouts, logging/observability, secrets management, authn/authz, error handling patterns, existing test coverage, CI/CD gates. - Every third-party API/service the app calls — especially load-bearing if this run is about outbound rate limiting: enumerate them, any documented rate limits you can find in code/config/comments/vendor docs, and exactly how the app currently reacts to 429s/backpressure/timeouts from each (retries? backoff? queuing? nothing at all?). - Whether any existing project docs (README, CLAUDE.md, architecture notes) describing current NFR posture are trustworthy — verify against actual code rather than assuming they're current; call out anything stale. ## Step 2 — Write a self-contained, repo-grounded brief Write it to `docs/productionization/--BRIEF.md` (create the directory if needed). It must stand alone — the agent executing it in Step 3 has no memory of this conversation. Include: - **Mission** — the investigating agent acts as a multi-disciplinary production-readiness review team (performance engineer, security engineer, SRE/capacity planner, API-integration architect, technical writer) auditing this specific codebase — not a generic checklist exercise. - **Grounding section** — every verified fact from Step 1 (stack, deployment target, what NFR mechanisms already exist, the third-party dependency inventory, any stale-doc warnings), phrased as verified facts, so the agent starts from reality instead of re-deriving it or guessing. - **Review categories** — always in scope unless this run's focus explicitly narrows them out (state clearly whether this run narrows scope to one category or just weights it more heavily within a full sweep): - Performance - Efficiency (compute/memory/cost, not just latency) - Security - Capacity (what load does this actually fall over at, and where's the ceiling) - Extensibility (how much pain does the next feature/integration cost, architecturally) - Rate limiting — **inbound**: is this app's own surface (API routes, webhooks, public endpoints) protected against abuse/overload? - Rate limiting — **outbound**: for every third-party API/service the app depends on, is there real backoff/retry/concurrency-control/circuit-breaking, or does it just hammer the API and hope? - Other NFRs the agent should proactively identify and is expected to go looking for even though they're not enumerated above — explicitly prompt for: observability/monitoring/alerting, resilience & error handling, logging & audit trails, secrets/credentials management, backup & disaster recovery, dependency/supply-chain health, cost efficiency, compliance considerations (if applicable to the domain), deployment & rollback safety, operational runbooks/documentation, test coverage & CI/CD gates. - **This run's focus** — the resolved emphasis/narrowing from Step 0, stated explicitly. - **Working method**: - **Read-only.** Never edit application code, never run destructive or state-changing commands, never commit, stage, or push anything. - Verify claims empirically wherever you safely can without modifying anything — run the app locally, exercise real endpoints, read actual response headers/timings/logs, run the *existing* test suite — but do not add, change, or commit code to do so. - Work autonomously without pausing to ask questions. If something is genuinely ambiguous or needs a business/human judgment call (budget, risk appetite, compliance posture), record it as an open question in the report rather than stopping. - There is no time limit — investigate as long as it takes to be thorough. Depth over speed. - **Required report structure** (so every run is consistent and comparable over time) — write the final report to `docs/productionization/--REPORT.md`: 1. **Executive summary** — a few sentences: overall production-readiness verdict, top 3–5 risks. 2. **Findings**, grouped by category. Each finding needs: severity (Critical/High/Medium/Low), one-line summary, concrete evidence (real `file:line` references — no vague claims), a concrete failure scenario (what breaks, under what real-world condition — mirror the rigor of "concrete inputs/state → wrong output/crash", not generic advice), and a recommended action. 3. **Tangible action list** — a flat, prioritized checklist derived straight from the findings, usable directly as a backlog. 4. **Phased remediation plan** — group actions into phases (e.g. "before any real traffic", "before scaling up", "nice to have"), noting rough effort and any dependencies between phases. 5. **Open questions** — anything needing a human/business decision rather than a pure engineering call. ## Step 3 — Launch the investigation 1. Determine the model: default to `fable`. If the resolved focus (inline text or customization file) explicitly requests a different model (e.g. "model:sonnet", "use opus"), honor that instead. 2. Launch via the Agent tool with that model, `run_in_background: true`, instructing it to read the brief file in full and execute it exactly, writing its report to the path specified in the brief. 3. Do not poll or wait. Tell Simon the investigation has been launched, where the brief lives, and that you'll relay results when it completes. ## Step 4 — When it reports back - Read the produced report yourself and spot-check a handful of its `file:line` claims against the real repo before relaying anything — don't take it on faith. - Give Simon a concise summary: top findings by severity, the prioritized action list, where the full report and plan live. Don't dump the entire report inline. - Do not implement anything from the findings yourself — this skill's job ends at the report. Acting on it is a separate, explicit follow-up. ## Notes - This skill produces documentation only, on purpose — it's meant to run repeatedly over a project's life with different focuses (e.g. first an outbound-rate-limiting-specific run, later a full sweep, later a security-specific pass), and `docs/productionization/` becomes a running, dated audit trail. Don't collapse runs into one file. - The brief this skill writes should read like a grounded engineering document, not a generic checklist: every claim in it should be something you actually verified in Step 1, not boilerplate. That rigor is the entire point — it's what lets the investigating agent spend its time finding real problems instead of re-discovering facts about the repo it's sitting in. - Deliberately does not `git add`/`commit`/`push` anything, including its own brief/report files — leave them as new, uncommitted files for Simon to review and commit himself once he's read them. ```` ```bash theme={null} cd /path/to/your/project claude ``` ``` /productionize ``` or with a focus, e.g. `/productionize focus heavily on outbound rate limiting`. The skill launches a `model: fable` background agent per run by default. That draws from the same account-level usage/rate limits as any other model on that machine — there's no separate quota for it.