A Practical Workflow for Contributing to a Large, Structured Codebase

This is the workflow I follow before I use AI agents to implement any feature or bug fix. 🧭 Requirements/Specification ↓ Design/Architecture ↓ AI Code Generation ↓ Human Review ↓ Build & Static Analysis ↓ Testing & Validation ↓ Defect Resolution ↓ Security & Compliance Review ↓ Release ↓ Production Monitoring vs Claude Code ↓ Implements feature ↓ Codex QA Agent ↓ Runs application ↓ Tests happy path ↓ Tests edge cases ↓ Tests error handling ↓ Produces QA report This will resolve the self-review bias, confirmation bias, or AI-to-AI bias. 1️⃣ Understand Before Writing Code Before touching any code, I try to understand what I'm building and why . I usually start by reading: specs/<module>/<TICKET>-<slug>.md plan/<module>/<TICKET>-<slug>.md status.md Then I review the project conventions: specs/CONVENTIONS.md specs/conventions/core-porting.md Finally, I read the existing implementation (entities, services, mappers, etc.) so my changes follow the existing architecture instead of introducing a new style. 💡 Pro-Tip Good code fits into the codebase. Great code looks like it was always there. 2️⃣ Plan the Change Once I understand the requirements, I identify which architectural layers are affected. I always respect the dependency order: Schema / Entities / DAOs ↓ Mappers / DTOs ↓ Service Layer ↓ Application Layer ↓ Controllers I don't jump ahead of dependencies. If a change is complicated or ambiguous, I document the approach before writing code. --- ## 3️⃣ Write the Code While implementing, I follow the repository's rules. Some examples: | Rule | Detail |---|---|---| | DTOs | Generated from `schema.yml` — never handwritten | | Status values | Sourced only from the Core Porting specification | | Traceability | Every ported behavior includes a source citation | Citation formats I use: - `← Source <path>` - `← PS §...` - `← BR-###` Beyond repository rules, I also try to: - ✅ Match existing naming conventions - ✅ Keep comments minimal and meaningful - ✅ Make small, focused chang