Skip to content

Samsen Internal Framework

This is Samsen's internal framework content for Design Systems. It is read-only reference material.

The Last Mile Problem — From Generated Code to Production

The Problem

Every AI coding tool can generate a component. Ask any LLM to "build a card component with React" and you'll get working code in seconds. Demos look impressive.

But the demo isn't the hard part. The hard part is shipping that component to a real production codebase. This is the last mile problem.

What the Last Mile Looks Like

Taking AI-generated code from "works in isolation" to "merged into production" requires:

Matching Existing Patterns

Production codebases have conventions:

  • File naming and directory structure
  • Import patterns and module boundaries
  • State management approaches
  • Error handling conventions
  • Testing patterns and coverage requirements

AI-generated code that ignores these conventions creates review friction, merge conflicts, and technical debt. It might work, but it doesn't fit.

Respecting Architectural Constraints

Real projects have architectural decisions that AI doesn't know about:

  • "We use server components for this route"
  • "All data fetching goes through this service layer"
  • "These components are lazy-loaded"
  • "We're migrating away from this pattern — don't add new instances"

Without this context, AI generates code that's technically correct but architecturally wrong.

Working in the Dependency Tree

Production components don't exist in isolation:

  • They depend on shared utilities, hooks, and contexts
  • They need to work with the existing CSS/styling approach
  • They must be compatible with the build system (bundler, transpiler, etc.)
  • They may need to handle server/client boundaries

AI-generated code that introduces new dependencies, conflicts with existing ones, or breaks the build isn't shippable.

Passing Quality Gates

Production code must pass:

  • Linting (ESLint, Prettier, Stylelint)
  • Type checking (TypeScript)
  • Tests (unit, integration, visual regression)
  • Accessibility checks
  • Bundle size budgets
  • CI pipeline

AI that generates unlinted, untyped, untested code creates work rather than saving it.

Solving the Last Mile

1. Context Engineering

The last mile problem is fundamentally a context problem. AI generates bad production code because it lacks production context. The solution is providing that context systematically:

  • CLAUDE.md with architectural conventions
  • Component spec with token usage and behavior requirements
  • Example files that demonstrate existing patterns
  • Design system tokens that define the valid values

See: ../ai-assisted-design/context-engineering.md

2. Iterative Approach

Don't expect AI to nail the last mile in one shot. Use an iterative workflow:

  1. Generate the initial component
  2. Run linting, type checking, tests
  3. Feed errors back to AI: "Fix these lint errors" / "This type is wrong" / "Add tests matching this pattern"
  4. Review in browser
  5. Iterate until it passes all quality gates

This is the same review cycle you'd use with a junior developer, but faster.

3. Working Inside the Codebase

The critical differentiator of Claude Code (vs. playground-style AI tools) is that it operates inside the project:

  • It can read existing files and understand patterns
  • It can run the build and see errors
  • It can execute tests and see failures
  • It has access to the full dependency tree

This is why the Samsen methodology uses Claude Code rather than copy-pasting from ChatGPT or similar tools. The AI needs to be in the codebase to solve the last mile.

4. Git-Based Workflow

Production shipping happens through git:

  • Claude Code creates a branch
  • Makes changes (new components, modifications, token updates)
  • Commits with meaningful messages
  • Opens a PR

The designer reviews the PR — not the code line by line, but the visual output and the diff summary. If it looks right and passes CI, it's ready to merge.

This gives the designer a production workflow without requiring them to understand the code. The PR is the quality gate. CI is the automated reviewer. The designer is the final arbiter of intent.

Why Most AI-Design Tools Fail Here

Most "AI for design" tools focus on generation — turning a design into code. They produce code that works in a sandbox but can't be dropped into a real project. Common failure modes:

  • Export-and-forget — Generate code, give it to the user, done. No iteration, no codebase awareness.
  • Framework assumptions — Generate React when the project uses Vue. Or generate React 17 patterns in a React 19 codebase.
  • Styling conflicts — Generate inline styles or new CSS files that conflict with the project's styling approach.
  • No testing — Generating components without tests means someone else has to write them.
  • Static snapshot — Generate code once. When the design changes, generate again from scratch rather than iterating.

The Shipping AI Designer framework solves these by keeping AI in the codebase (not a separate tool), providing full context (not just a design file), and using iterative conversation (not one-shot generation).