box-nestjs-monorepo/docs/CODEX_CI_CHECKLIST.md

Codex + CI Checklist

Goal: Use Codex as a powerful assistant without breaking the Box System or letting unreviewed AI code slip into production.

This checklist is for every feature or refactor where Codex is involved.

---

1. Before You Ask Codex

• Create a feature branch from main or develop: - Example: feature/auto-registration-device-code.
• Confirm docs are up to date: - docs/ARCHITECTURE.md - docs/SYSTEM_OVERVIEW.md - docs/DEVELOPMENT_CHECKLIST.md - docs/ROADMAP.md
• Clarify the task in your own words: - What are you changing? - Which app? (box-mgnt-api, box-app-api, box-stats-api) - What are the constraints? (e.g. “no breaking changes”, “BigInt timestamps”)

---

2. When Prompting Codex

• Mention the project context: - “We are in box-nestjs-monorepo (NestJS + TypeScript, MySQL, Mongo, Redis).”
• Tell Codex to read the docs referenced in .codex/config.json.
• Use a structured prompt (from docs/CODEX_PROMPTS.md), including: - Architecture reference. - Tech stack. - Constraints: - TypeScript only. - NestJS patterns. - BigInt epoch for timestamps. - Avoid breaking changes.
• Ask for a plan before code: - “Step 1: Summarize current design.” - “Step 2: Propose changes and list affected files.” - “Step 3: Wait for confirmation before generating TypeScript code.”

---

3. Reviewing Codex’s Plan

• Check the alignment with architecture: - Does the plan match ARCHITECTURE.md and API_FLOW_DIAGRAMS.md?
• Check scope vs roadmap: - Is the change consistent with the current phase in ROADMAP.md?
• Check dependencies & impact: - Which modules, services, DTOs, and DB schemas are affected?
• If anything feels off: - [ ] Ask Codex to revise the plan. - [ ] Or narrow the scope.

Do not accept auto-generated code if the plan itself looks wrong.

---

4. Generating Code with Codex

• Ask Codex to: - Generate TypeScript code in small chunks (one module/file at a time). - Clearly label which file each snippet belongs to.
• Verify: - [ ] Uses TypeScript and NestJS decorators correctly. - [ ] Respects BigInt timestamps for date/time fields. - [ ] Uses existing conventions from libs/common, libs/core, libs/db.
• Manually paste code into files (or let Codex apply edits, but still review them).

---

5. Local Verification (Before Commit)

• Run TypeScript compilation: - pnpm build or pnpm lint + pnpm tsc equivalent.
• Run linters & formatters: - pnpm lint - pnpm format (if applicable)
• Run tests: - pnpm test (or app-specific test commands)
• If schema changed: - [ ] Run Prisma format & generate: - pnpm prisma:format - pnpm prisma:generate - [ ] Apply local migrations to dev DB (if needed).
• Test key endpoints manually with curl/Postman: - Especially: - New/modified endpoints. - Auth-protected routes. - Redis-related flows (ad placement, stats events).

If anything fails, fix it yourself or ask Codex for a focused correction (with error logs included in the prompt).

---

6. Preparing the Pull Request

• Create a clear PR title: - Example: feat(app-api): auto-register users by device_code.
• In the PR description, include: - [ ] Summary of the change. - [ ] Which parts were generated or heavily assisted by Codex. - [ ] Link to relevant docs in docs/ (architecture, roadmap). - [ ] Any potential risks or backward-compatibility notes.
• Attach testing evidence: - [ ] Commands you ran (lint, test, build). - [ ] Screenshots/logs for manual endpoint tests if useful.

---

7. Code Review (Human + Codex-Assisted)

Reviewer checklist:

• Understand the functional goal of the change.
• Confirm architecture alignment: - Modules/controllers/services match design.
• Check for: - [ ] Hardcoded secrets or credentials. - [ ] Direct DB access bypassing libs/db abstractions. - [ ] Inconsistent DTOs or response shapes. - [ ] Missing validation on inputs.
• Check error handling & logging: - Are important failures logged in a structured way?
• Optionally, use Codex again: - Ask it to review a specific file/method for: - Complexity. - Edge cases. - Missing null/undefined handling.

---

8. CI Integration

• Ensure your CI pipeline runs on each PR: - Lint - Tests - Build (optional)
• If CI fails: - [ ] Fix locally. - [ ] Re-run tests. - [ ] Push updates.
• Do not override CI protections** to merge failing PRs**, even if Codex generated the code.

---

9. After Merge

• Monitor logs/metrics in the relevant environment: - Error rates. - Latency. - Queue depth (for stats).
• If issues appear: - [ ] Create a hotfix branch. - [ ] Optionally use Codex to assist in debugging, but: - Keep changes small and review carefully.

---

10. Golden Rules

1. Codex is a power tool, not an excuse to skip thinking.
2. Docs in docs/ are the source of truth; Codex must follow them.
3. Never merge Codex-generated changes without:
   • Passing tests.
   • At least one human review.
4. When in doubt:
   • Reduce the scope.
   • Add more tests.
   • Ask Codex for a design explanation before touching code.