10. Development Workflow: Existing Code Integration

← Back to Table of Contents | Previous: New Product Workflow | Next: File Hierarchy →

10.1 When to Use This Workflow

Use this workflow when integrating an existing codebase for ongoing maintenance and development with Kiro. The code already exists — you need to make it Kiro-compatible.

10.2 Phase 1: Assessment (Week 1)

Step 1: Analyze the Existing Codebase

Before configuring Kiro, understand what you have:

1. Identify existing module boundaries (or lack thereof)
2. Map dependencies between components
3. Assess test coverage (if any)
4. Identify the build and deployment process
5. Document existing conventions (naming, structure, patterns)

Step 2: Define Module Boundaries

If the codebase is a monolith, identify logical boundaries:

Existing code analysis:
├── Which components are independent?
├── Which components share state?
├── Where are the natural seams?
└── What are the external dependencies?

Map existing directories to modules. If the code is not modular, plan a gradual restructuring.

Step 3: Establish a Test Baseline

This is critical. Before Kiro starts modifying code, you need a safety net:

1. Run existing tests (if any) and record coverage
2. If no tests exist, write characterization tests for critical paths
3. Set up CI to run tests on every PR

Without tests, Kiro modifications cannot be validated.

10.3 Phase 2: Kiro Onboarding (Week 1–2)

Step 4: Add Kiro Configuration

1. Create the .kiro/ directory structure
2. Write steering rules that match the existing codebase conventions

Key difference from new product: steering rules must describe the existing architecture, not an ideal one.

Example for a legacy Express.js app:

# Global Rules (adapted for existing codebase)

## Architecture (as-is)
- Routes are defined in `routes/` directory
- Business logic is in `controllers/` (note: not ideal, but current state)
- Database access uses raw SQL in `db/` directory
- No service layer exists yet

## Migration Rules
- New code follows service/repository pattern
- Existing code is refactored incrementally, not rewritten
- When modifying a controller, extract business logic into a service
- When modifying a db query, wrap it in a repository

## Testing Rules
- All NEW code must have unit tests
- When modifying EXISTING code, add tests for the modified functions
- Do not rewrite existing tests unless they are broken

Step 5: Configure Module Ownership

Even if the existing code is not perfectly modular, assign ownership:

routes/auth/*       → Dev 1 + Kiro
routes/billing/*    → Dev 2 + Kiro
routes/orders/*     → Dev 3 + Kiro
controllers/*       → Follows route ownership
db/migrations/*     → Shared (human review required)

Step 6: Set Up CI/CD

If CI/CD does not exist: 1. Add .gitlab-ci.yml with lint + test stages first 2. Add build and deploy stages incrementally 3. Do not try to Terraform everything on day one

If CI/CD already exists: 1. Add the missing stages (security scan, test coverage reporting) 2. Ensure PR-based validation is enforced

10.4 Phase 3: Incremental Improvement (Ongoing)

Step 7: Gradual Modularization

As Kiro works on features and fixes, the codebase improves incrementally:

Sprint N:   Fix bug in auth → extract AuthService → add tests
Sprint N+1: Add feature to billing → create BillingService → add tests
Sprint N+2: Refactor orders → create OrderRepository → add tests

Each modification leaves the code slightly better structured.

Step 8: Gradual Infrastructure Migration

If infrastructure is manually managed:

1. Start by Terraforming the easiest resources (ECR, S3 buckets)
2. Import existing resources into Terraform state
3. Gradually add more resources
4. Never do a big-bang migration

terraform import aws_ecs_cluster.main arn:aws:ecs:...

10.5 Recommendations for Existing Code

10.6 Anti-Patterns to Avoid

← Back to Table of Contents | Previous: New Product Workflow | Next: File Hierarchy →