Skip to content

AI Driven Development

Jump to bottom
Oleksandr Geronime edited this page Jun 27, 2026 · 4 revisions

The challenge with AI in large systems is scope. Unbounded tasks produce unpredictable results. SERP solves this structurally — framework, generator, and tooling together reduce every AI task to a bounded implementation problem with clear contracts and hard scope limits.

Why SERP Works Well with AI

Building a large distributed system with AI is hard because AI produces unpredictable results when given unbounded scope. SERP solves this structurally.

Critical code lives in libraries — AI never touches it

Threading, event loop dispatch, IPC marshaling, lifecycle sequencing, watchdog enforcement — all of this lives in the compiled SERP framework libraries. AI sessions operate on impl files in src/. There is no way to accidentally break the framework from a service session.

Glue code is generated — AI never writes it

Transport adapters, proxy/stub classes, process entry points, CMake wiring, service registration — everything that connects the pieces together is generated by serpgen from specs. It is correct by construction. AI does not write it and does not need to understand it.

AI only writes business logic

What remains after framework and generator cover their ground is purely business logic — the part that cannot be covered by specs because of its variability. This is exactly the bounded, well-scoped problem that AI handles well: implement ClimateManager::onSetTemperature, not "wire up the IPC layer."

Specs are contracts between AI sessions

The Architecture session writes IClimateManager.sidl.yaml. Every subsequent session — Service, HMI, Debug — works from that contract. The interface is authoritative. The generator enforces it at compile time. An AI implementing a service cannot diverge from what the architect specified.

The Three-Phase Workflow

Phase 1 — Architecture

Session role: system-architect
Allowed writes: specs/services/**, specs/interfaces/**, specs/deployments/**
Tool: Architecture session in the SERP VS Code panel

The architect session designs the full system decomposition:

  1. Identify service boundaries, responsibilities, and dependencies
  2. Define interface contracts in SerpIDL (methods, properties, notifications, types)
  3. Define deployment topologies (which services run in which processes, which transport)
  4. Validate specs with serpgen validate — catches inconsistencies before any code is written
  5. Write an architecture summary that child sessions inherit automatically

The session follows a structured workflow: requirements → research → decomposition → validation → review → revision. Unresolved design questions block stage completion — forcing explicit decisions rather than implicit assumptions.

Output: A complete specs/ tree. Running serpgen generate-workspace after this phase produces all interfaces, base classes, and process entry points.

Phase 2 — Service Implementation

Session role: service-implementer
Allowed writes: src/services/<group>/<service>/**, tests/services/<group>/<service>/**
Tool: Service session per service in the SERP VS Code panel

Each service is implemented in an isolated session. Sessions for different services can run in parallel — they cannot touch each other's files.

Each service session automatically receives:

  • The architecture summary from Phase 1 (design decisions, constraints, rationale)
  • The interface spec for this service (what methods it must implement)
  • The generated base class (method signatures, property declarations, notification wiring)
  • Existing implementation files (if resuming work)

The AI implements handlers, fills in lifecycle methods, mutates properties, fires notifications — all strictly within the generated interface contract. The scope guard blocks any write outside src/services/<group>/<service>/.

Key property: adding a new service to the system means opening a new session. Sessions do not need to coordinate. The specs coordinate them.

Phase 3 — Debug and Fix

Session role: runtime-investigator (Analyze/Debug) or deployment-fixer (Fix)
Allowed writes: Fix role — src/services/**, tests/**
Tool: Debug session tied to the active deployment

Debug sessions have access to a running system. The AI does not guess — it observes.

Structured debug cycle:

List methods → Call method → Observe result → Form hypothesis → Call again → Fix → Build → Test

Using the serp_runtime_call MCP tool, the AI can:

  • Call any public method on any running service: ClimateManager.SetTemperature, MediaManager.Play
  • Read current property values: current temperature, playback state
  • Subscribe to notifications: observe events as they fire

This is the same capability exposed by the Runtime Inspector in the VS Code UI — but available directly to the AI session, enabling automated investigation without human relay.

Debug sessions inherit summaries from all parent sessions — the architecture context and all service implementation summaries. The AI debugs with full awareness of design intent.

Scope Isolation and Parallelism

Every session has a hard-enforced write scope. This is not a convention — it is a pre-tool-use hook that blocks writes at the shell level before they reach the file system.

Session Can write Cannot write
Architecture specs/ src/, gen/, tests/
Service (cabin/Media) src/services/cabin/MediaService/, its tests All other services, specs/, gen/
HMI src/hmi/<app>/, specs/hmi/ src/services/, gen/
Fix src/services/**, tests/** specs/, gen/
All sessions — gen/** (always forbidden)

This makes parallel AI sessions safe. An architect session and three service sessions can run simultaneously with no risk of collision.

Logging as AI Infrastructure

SERP logs all inter-service communication and all lifecycle events automatically, in a uniform format — this is not application-level logging added by developers, it is framework-level instrumentation.

Every method call between services is logged with:

  • Caller thread and callee thread
  • Method name and arguments
  • Timing

Every service lifecycle transition is logged:

  • Created, Initializing, Initialized, Deinitializing, Deinitialized

Because the format is consistent and predictable across the entire system, AI can analyze logs without custom parsing logic. A debug session can read a log and immediately understand which service called what, in what order, and where a chain broke — without needing deployment-specific knowledge about log formats.

Context Inheritance

Sessions form a hierarchy. Child sessions inherit summaries from parents automatically:

architecture::system
    └── service::cabin/ClimateManager
    └── service::cabin/MediaManager
    └── service::platform/VehicleHal
            └── sequence::cabin/ClimateManager/HandleSetTemperature

When a Service session opens, it receives the architecture summary — the design decisions, constraints, and rationale from Phase 1. When a Fix session opens, it receives architecture and all service summaries. Each level of AI work builds on what came before without re-reading everything from scratch.

Summaries are stored in .serp/ai/summaries/ and updated by the AI at the end of each session. They are the institutional memory of the build.

Structured Workflows and Validation Gates

Sessions do not run as open-ended chats. Each role follows a structured workflow with named stages and completion criteria.

Example: Architecture workflow stages

Stage Goal Completion criteria
requirements_analysis Understand the problem No unresolved critical questions
research Collect domain knowledge Key artifacts written
decomposition_draft Write specs serpgen validate passes
validation Verify consistency IR dump clean, no circular deps
hostile_review Attack the design Review artifact written
revision Fix findings Revalidation passes

Unresolved critical questions block stage advancement. Validation failures trigger automatic loop-back to the fix stage. The AI cannot declare work done until all gates pass.

Validators run automatically at the right stages:

  • generator_validate — runs serpgen validate on specs
  • build — CMake build passes
  • service_tests — component tests for the modified service pass
  • scope_lock — all written files are within allowed scope

Summary

Property What it means for AI
Framework libraries AI cannot break threading, IPC, lifecycle — not in scope
Code generation AI never writes glue — only business logic remains
Spec contracts Architecture AI defines what; service AI implements it; no negotiation
Scope enforcement Hard file-system-level blocks — AI parallelism is safe by construction
Runtime access Debug AI calls live services, reads state, observes events in real time
Uniform logging AI analyzes logs without custom parsers
Summary inheritance Each session builds on prior sessions — context is layered, not re-read
Workflow stages Structured progression with validation gates — AI cannot skip steps

See Also

SERP Wiki

Getting Started

The Development Model

Architecture Language

Code Generator

Framework Internals

VS Code Plugin

Examples

Clone this wiki locally