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 changes instead of massive rewrites

---

## 4️⃣ Verify Everything

After implementation comes verification.

I run the relevant module tests:

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

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!* 👇