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//-.md plan//-.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 ` - `← PS §...` - `← BR-###` Beyond repository rules, I also try to: - ✅ Match existing naming conventions - ✅ Keep comments minimal and meaningful - ✅ Make small, focused changes instead of massive rewrites --- ## 4️⃣ Verify Everything After implementation comes verification. I run the relevant module tests: Enter fullscreen mode Exit fullscreen mode bash mvn -pl test Locally I usually include `-am`, since Liquibase is disabled and schema changes need to be applied first. Because this repository doesn't currently have independent QA, I also: - Verify that all tests pass - Run mutation tests if coverage is uncertain - Exercise the runtime flow instead of relying only on successful compilation If something fails, **I report it honestly** rather than hiding the failure. 🛠️ --- ## 5️⃣ Finish Cleanly Before considering the work complete, I: - Reference the requirement or rule IDs implemented - Update `status.md` only after owner approval - Commit and push only when requested - Create an ADR if I intentionally deviate from established conventions If there's an exception, it should be **documented — not silently introduced**. --- ## 🔁 The Entire Workflow Enter fullscreen mode Exit fullscreen mode plaintext Read the specification ↓ Read the conventions ↓ Understand the existing code ↓ Plan the implementation ↓ Write minimal changes ↓ Test and verify ↓ Report results honestly Following this process helps me write code that integrates naturally with the existing codebase, minimizes regressions, and makes future maintenance much easier. --- *If you follow a similar workflow (or have tweaks that work better for your team), I'd love to hear about it in the comments!* 👇 Enter fullscreen mode Exit fullscreen mode