Claude Code as Engineering Copilot

The Setup

Vivolar uses Claude Code (Anthropic’s CLI) as an engineering copilot. The integration goes beyond simple code completion — it’s a structured collaboration between the developer and the AI assistant.

The key enabler is CLAUDE.md, a project-level instruction file that provides Claude Code with:

• Architecture rules (event-driven, household-scoped, module boundaries)
• Development conventions (package structure, DTO patterns, test strategy)
• Process rules (TDD loop, documentation requirements, commit conventions)
• Available tools and scripts

How It Works

Skills System

Commonly repeated workflows are packaged as “skills” — reusable prompts that encode project-specific knowledge:

• /implement-task — follows the TDD loop: read spec → study patterns → implement → test → fix → document → commit
• /refinement — leads a backlog refinement session as a Product Owner
• /plan-sprint-tasks — breaks features into implementable TDD tasks
• /backend-dev and /frontend-dev — apply stack-specific conventions

Automation Scripts

Headless scripts extend Claude Code’s capabilities:

• run-sprint.sh — autonomous sprint execution with test gates
• implement-task.sh — single-task implementation loop
• pre-deploy-validate.sh — pre-deployment validation pipeline
• format-hook.sh — auto-formatting after every edit

Hooks

PostToolUse hooks run automatically after every file edit:

• Java files: spring-javaformat:apply + mvnw compile
• TypeScript/CSS/JSON: prettier --write

This means the AI’s output is always formatted correctly, and compile errors surface immediately.

The Collaboration Model

The human (me) owns:

• Architecture decisions — what patterns to use, when to deviate
• Priority and scope — which tasks matter, what’s out of scope
• Quality judgment — reviewing AI output, catching subtle issues
• Deploy decisions — when to ship, what environments

Claude Code handles:

• Implementation velocity — generating boilerplate, writing tests, wiring up DTOs
• Pattern consistency — following established conventions across 12+ packages
• Documentation — keeping sprint docs, TODOs, and specs in sync
• Exploration — searching the codebase, understanding existing patterns before making changes

Results

The collaboration has been effective because:

1. Context is preserved in code. CLAUDE.md, skills, and hooks encode knowledge that would otherwise be lost between sessions.
2. Guardrails prevent drift. Architecture rules, test gates, and formatting hooks keep the output consistent.
3. The human stays in the loop. Every commit is reviewed, every deploy is approved, and design decisions remain with the developer.

Honest Limitations

• AI-generated code needs review. Subtle issues (wrong import path, incorrect enum value) slip through if you trust blindly.
• Complex refactorings still need human planning. The AI excels at well-defined tasks, not ambiguous architectural shifts.
• Session context is finite. Long sessions accumulate context, but each new session starts fresh (with CLAUDE.md as the foundation).