Solving Over-Engineering in AI-Generated Dev Environments

The Wrong Unit of Work: What Happened When I Built My Dev Environment using Claude Code

Amitai Levy used Claude Code to build a clinical trials platform at PhaseV. The initial AI-generated Docker environment required 15 commits across 10+ sessions to dismantle unnecessary complexity.

Why This Matters

The technical reality of AI agents often defaults to delivering a comprehensive package rather than incremental building blocks. This monolithic approach results in intertwined, fragile systems where individual components—like custom shell scripts and port arithmetic—become technical debt before the first deploy. By shifting the unit of work from total delivery to milestones, engineers can steer implementation early, preventing the simplification marathons that cost significant developer time.

Key Insights

• Claude Code initially generated a custom ‘pv’ shell script and port offset arithmetic for multi-instance support, which the user later removed.
• Simplification reduced the .env file from approximately 30 variables to just 2 by moving defaults into service-specific compose files.
• The final architecture utilized a 15-line compose.yaml with ‘include’ directives and ‘compose.infra.yaml’ to replace monolithic scripts.
• Multi-instance support was achieved through standard Docker Compose project names rather than custom port-management logic.
• A new ‘CLAUDE.md’ configuration was established to force the AI to propose milestones and build the smallest working version first.

Working Examples

Configuration rule added to CLAUDE.md to enforce incremental development.

## Lead with increments For complex features, act as a tech lead managing the process: 1. Propose a sequence of increments — not a detailed plan, just the milestones. 2. Implement the first increment autonomously. Build the smallest complete version that works. Deliver it. 3. Check in briefly before the next increment. Let the user decide if more is needed. Often the first increment is enough.

Practical Applications

• PhaseV clinical platform: Orchestrating microservices using Docker Compose ‘include’ and project names instead of custom port-management scripts.
• Pitfall: Over-engineered monolithic delivery by AI agents, resulting in 10+ sessions of unwinding code to reach a maintainable 15-line configuration.
• Tech Lead Prompting: Configuring CLAUDE.md to require a sequence of milestones before implementation begins.
• Pitfall: Shared Dockerfiles for multiple microservices, causing coupling that prevents individual service ownership of build environments.

References:

• https://dev.to/amitaile/the-wrong-unit-of-work-what-happened-when-i-built-my-dev-environment-using-claude-code-5a6