Codex Tips

// Understand First

1. Let Codex Understand Before It Changes Anything

Starting with "just edit it" usually creates more rework.

Add a filter to this page, just go ahead and change it

That leaves the edit surface, the relevant modules, and the constraints unspecified. Codex ends up reading and guessing at the same time.

First, read these files and summarize the current structure:
- src/components/ComparisonTable.tsx
- src/data/platforms.json
- src/app/[locale]/page.tsx

Tell me where the filtering logic should live and which files you plan to change.
Do not write code yet.

// Constrain Scope

2. Constrain the Edit Scope

Codex is proactive. If you do not narrow the boundary, small changes can sprawl.

Specify These Three Things

Only modify src/components/LocaleToggle.tsx
Goal: fix line wrapping on mobile
Constraints:
- Do not change other components
- Do not refactor style variables
- Keep the change minimal

// File Paths

3. Use File Paths, Not Giant Pasted Snippets

Codex works inside the repo. Your job is to point it at the right entry points, not to dump code into chat.

Better Context Pattern

• Give exact paths
• Say where to start reading
• Mention upstream and downstream files when the logic crosses layers

The issue is likely across these files:
- src/components/PlatformDetail.tsx
- src/lib/platforms.ts
- src/data/platforms.json

Trace the data flow from PlatformDetail -> platforms.ts -> platforms.json
and find the exact reason the "Codex" badge is not rendering.

// One Goal

4. Push One Goal Per Round

Codex can do a lot in one go. That does not mean you should ask for everything at once.

Help me:
1. Add a new guide article
2. Rewrite the homepage copy
3. Fix sitemap
4. Improve SEO
5. Redesign the guide cards too

Do one thing first: add a new /guide/codex-tips article.
Requirements:
- Support zh and en
- Match the style of claude-code-tips
- Add it to the guide list and sitemap

Do not make other changes yet.

// Plan First

5. Ask for a Plan Before Implementation

For anything beyond a trivial edit, asking Codex for a short plan first is usually worth it.

Do not write code yet.
Based on the current repo, give me an implementation plan in 3 steps or fewer:
- which files you will change
- what each file change will do
- where regressions are most likely

Wait for my confirmation before editing.

This lets you stop bad direction before it reaches the filesystem.

// Acceptance

6. Define Acceptance Criteria

If you never define "done", Codex cannot reliably optimize toward it.

Definition of done:
- The new article route works in both languages
- Both language versions are complete
- The guide index shows the new card
- sitemap includes codex-tips
- next lint passes if the project supports it

// Verify

7. Require Self-Verification

Do not let the workflow end at "code written". Make it verify what it changed.

After the change is done, continue with two steps:
1. Run the relevant validation commands in this repo (lint / build / tests if available)
2. Tell me what you verified and what remains unverified

Why This Matters

• It shifts Codex from "generate code" to "deliver a result"
• It catches missing imports, route mistakes, type issues, and broken references early
• It gives you enough signal to decide whether the patch is ready

// Review

8. Ask Codex to Review Its Own Patch

Many bugs are not implementation failures. They are review failures.

Before you finish, do a short review of your own patch.
Check for:
- missed entry points
- zh/en inconsistencies
- broken links or bad paths
- unnecessary edits

If you find issues, fix them before reporting back.

// AGENTS.md

9. Put Standing Rules in AGENTS.md

If you repeat the same rules every session, write them down once in AGENTS.md.

# AGENTS.md

- Read relevant files before editing
- Prefer the minimum necessary change
- Run lint after code changes
- Final response must include: what changed, what was verified, remaining risks
- New pages must include metadata and sitemap updates
- Keep zh and en content in sync

That gives Codex a stable operating contract every time it enters the repo.

// Templates

10. Copy-and-Use Codex Prompt Templates

Add a new guide article with the slug codex-tips.
Requirements:
- Place it at src/app/[locale]/guide/codex-tips/page.tsx
- Support zh / en
- Match the style of src/app/[locale]/guide/claude-code-tips/page.tsx
- Add a card in src/app/[locale]/guide/page.tsx
- Add the slug in src/app/sitemap.ts

Read the related files first, give me a plan, then implement it.

Fix the missing guide slug in src/app/sitemap.ts.
Requirements:
- Only edit this file
- Do not refactor unrelated logic
- After the change, tell me which route entries were added

Investigate why the new guide card is not showing on the guide index.
Start from:
- src/app/[locale]/guide/page.tsx
- src/data/i18n.json
- src/app/sitemap.ts

Tell me the root cause first. Do not edit code yet.

// Summary

Summary

Codex productivity is mostly about collaboration boundaries, not prompt theatrics.

Use Codex like an executable engineering partner, not a generic chatbot, and the quality gets much more predictable.