Home Explore Help
Sign In
fct
/
box-nestjs-monorepo
2
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: 35dbeebbc0
Branches Tags
box-nestjs-mono...
/
docs
/
CODEX_CI_CHECKLIST.md

CODEX_CI_CHECKLIST.md 5.2 KB
History Raw

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.