| name | update-Codex-documentation |
| description | Update project documentation files (README.md, PROJECT_BRIEF.md, TECH_STACK.md, ARCHITECTURE.md, docs/API.md, docs/DATABASE.md, AGENTS.md) when significant changes occur. Use for feature additions, architecture changes, dependency updates, API/database modifications. Ensures consistency across all docs. |
Update Codex Documentation
Update project documentation systematically after significant changes. Keep all files consistent and accurate.
Core Principle: Documentation tells one cohesive story. Each file serves a specific audience but must reflect the same reality.
Modularize Instructions (Token Economy): Avoid packing everything into a single AGENTS.md. Prefer multiple focused docs (e.g., docs/setup.md, docs/api.md, docs/workflows.md) and reference them only when needed to reduce context bloat.
When to Use
✅ Adding/removing features
✅ Architecture or design pattern changes
✅ Dependency or tech stack updates
✅ API endpoints or database schema changes
✅ Project directory restructuring
✅ Development workflow changes
❌ Typo fixes (do directly)
❌ Code comments
❌ WIP features not yet merged
Documentation Files
| File | Audience | Purpose |
|---|
| PROJECT_BRIEF.md | Stakeholders, new devs | 30-sec overview |
| README.md | Developers | Setup, usage guide |
| TECH_STACK.md | Developers, DevOps | Tech inventory |
| ARCHITECTURE.md | Senior devs, architects | System design |
| docs/API.md | API consumers | API reference |
| docs/DATABASE.md | Backend devs, DBAs | Schema docs |
| AGENTS.md | Codex | Dev patterns |
| docs/setup.md | Developers | Setup details |
| docs/api.md | API consumers | API usage guide |
| docs/workflows.md | Developers | Workflow rules |
Change → File Mapping
New Feature:
- README.md (usage)
- docs/API.md (if adds endpoints)
- docs/DATABASE.md (if adds tables)
- ARCHITECTURE.md (if adds components)
- AGENTS.md (if changes patterns)
- PROJECT_BRIEF.md (if significant)
Tech Stack Change:
- TECH_STACK.md (always)
- README.md (setup instructions)
- ARCHITECTURE.md (if affects design)
- AGENTS.md (if affects workflows)
Architecture Change:
- ARCHITECTURE.md (always)
- README.md (overview section)
- AGENTS.md (patterns)
- PROJECT_BRIEF.md (if major)
API/Database Change:
- docs/API.md or docs/DATABASE.md (always)
- ARCHITECTURE.md (if changes contracts)
- AGENTS.md (if affects patterns)
- README.md (if affects usage)
Update Workflow
1. Understand Change (2-5 min)
Document:
- Type: Feature/Architecture/Tech Stack/API/Database
- What: One sentence description
- Impact: Who/what affected
- Breaking: Yes/No (what breaks)
2. Map to Files (1-2 min)
Order: Specific → General
- Technical Specs (API.md, DATABASE.md)
- Architecture (ARCHITECTURE.md, TECH_STACK.md)
- AI Instructions (AGENTS.md)
- User Guides (README.md)
- Overview (PROJECT_BRIEF.md)
3. Read Current State (2-3 min)
Read all affected files in parallel.
4. Update Systematically (10-20 min)
Per-file checklist:
5. Verify Consistency (2-3 min)
Check across all files:
6. Final Review (1 min)
Total: 15-30 minutes
Common Mistakes
❌ Updating only one file
# Updated README but forgot AGENTS.md
# Result: AI doesn't know new pattern
❌ Inconsistent terminology
# README.md: "Authentication Service"
# ARCHITECTURE.md: "Auth Module"
# AGENTS.md: "Login System"
# Pick ONE term everywhere
❌ Forgetting breaking changes
# Renamed API endpoint but README examples still use old path
# Add migration notes EVERYWHERE affected
❌ General → Specific order
# BAD: Update BRIEF first, then API.md
# GOOD: Update API.md first (precise), then BRIEF (summary)
Quick Reference
Update Order:
API/DB Specs → Architecture → Codex → README → BRIEF
Consistency Checks:
Terminology, Versions, Paths, Names, Features
Time Budget:
Small change: 5-10 min
Medium change: 15-30 min
Major refactor: 45-60 min
Summary
Process: Understand → Map → Read → Update → Verify → Review
Key Rules:
- Update specific docs first, general last
- Read all affected files before editing
- Keep terminology consistent
- Mark breaking changes everywhere
- Test examples before committing
- One reality, multiple perspectives
Remember: Documentation debt compounds fast. Update immediately when making changes.
