claw-code/.guardrails/docs/ai-dev/AI_ASSISTED_DEV.md

AI-Assisted Development Patterns

Version: 1.0.0 Last Updated: 2026-03-14 Applies To: ALL AI-driven development workflows, vibe coding sessions, agent-generated code

---

Purpose

This document defines how AI agents should build software at high velocity. Guardrails aren't constraints on speed — they're what enable it. When agents know the boundaries, they spend tokens on building instead of safety-checking.

Core Principle: The fastest development happens when agents follow proven patterns instead of inventing new ones.

---

The Vibe Coding Workflow

Vibe coding is AI-driven rapid development where agents generate, iterate, and ship at maximum speed. The guardrails in this framework make vibe coding safe by default.

The Speed Equation

Without Guardrails	With Guardrails
Agent generates code	Agent generates code
Agent second-guesses safety	Safety check (built-in)
Agent asks user for confirmation	Confirmation (pre-authorized)
Agent re-reads files for context	Re-read (trust the maps)
Agent checks accessibility	Manual a11y (patterns include it)
Result: 40% of tokens on building	Result: 90% of tokens on building

---

Decision Matrix: Ask vs Decide vs Halt

Not all decisions carry equal risk. Use this matrix to determine when agents should proceed autonomously, when to ask, and when to halt.

Risk Level: LOW — Decide Autonomously

Action	Example	Why Safe
UI component generation	Build a button, modal, card	Pre-validated patterns exist
Styling changes	Colors, spacing, typography	Design tokens constrain choices
Test writing	Unit tests, integration tests	Tests are additive, low-risk
Documentation updates	Comments, README sections	Non-breaking, easily reversed
Refactoring within scope	Rename variable, extract function	Scoped and verifiable

Risk Level: MEDIUM — Ask Before Proceeding

Action	Example	Why Ask
New dependency addition	Adding a package	Supply chain risk
API schema changes	New endpoint, field change	Affects consumers
Database migrations	Schema change	Data integrity risk
Configuration changes	Environment variables	Deployment impact
Cross-module refactoring	Changing shared interfaces	Cascade risk

Risk Level: HIGH — Halt and Confirm

Action	Example	Why Halt
Authentication changes	Login flow, token handling	Security-critical
Payment integration	Billing, IAP, subscriptions	Financial risk
Data model changes	User schema, permissions	Data loss risk
Infrastructure changes	Deploy config, CI/CD	Production impact
Deletion of any kind	Files, data, accounts	Irreversible

---

Design-Intent Preservation

When iterating rapidly, agents must preserve the original design intent across generations.

Style Anchors

Lock design decisions that should survive iteration:

// STYLE ANCHOR: Do not modify these design tokens
const DESIGN_ANCHORS = {
  colorPrimary: '#2563eb',    // Brand blue — locked
  borderRadius: '8px',        // Consistent rounding — locked
  fontFamily: 'Inter',        // Typography — locked
  spacingUnit: 4,             // 4px grid — locked
} as const;

// STYLE ANCHOR: Layout constants — do not modify during iteration
const GRID_COLUMNS: u32 = 12;        // Locked
const GUTTER_WIDTH: f32 = 16.0;      // Locked
const MAX_CONTENT_WIDTH: f32 = 1200.0; // Locked

// STYLE ANCHOR: Design tokens — locked across iterations
var DesignAnchors = struct {
    ColorPrimary string
    BorderRadius string
    MaxWidth     int
}{
    ColorPrimary: "#2563eb",  // Locked
    BorderRadius: "8px",      // Locked
    MaxWidth:     1200,        // Locked
}

Intent Logs

When making changes, log what was intended vs what was changed:

INTENT: Add dark mode toggle to settings
CHANGED: settings/ThemeToggle.tsx (new component)
CHANGED: settings/index.tsx (added toggle to layout)
PRESERVED: All existing settings, color tokens, layout structure

---

Prompt-to-UI Scaffolding

Component Generation Flow

1. Parse prompt → Extract requirements (a11y, performance, ethics)
2. Select pattern → Match to existing UI pattern from 2026_UI_UX_STANDARD.md
3. Apply constraints → WCAG 3.0+, performance budget, ethical review
4. Generate code → Using design tokens and anchored styles
5. Verify output → Automated checks (lint, a11y, performance)

Scaffold Templates

When generating UI components, start from these scaffolds rather than blank files:

// Standard accessible component scaffold
interface ComponentProps {
  /** Required for accessibility */
  'aria-label': string;
  /** Visual state */
  variant?: 'primary' | 'secondary' | 'ghost';
  /** Size following 4px grid */
  size?: 'sm' | 'md' | 'lg';
}

export function Component({ 'aria-label': ariaLabel, variant = 'primary', size = 'md' }: ComponentProps) {
  return (
    <div
      role="region"
      aria-label={ariaLabel}
      className={`component component--${variant} component--${size}`}
    >
      {/* Generated content */}
    </div>
  );
}

---

Iteration Safety

Diff-Before-Overwrite

MANDATORY: Before overwriting any file, generate and review the diff.

// Before overwriting, always:
// 1. Read current file content
// 2. Generate proposed changes
// 3. Diff current vs proposed
// 4. Verify intent is preserved
// 5. Apply changes

Rollback Points

Create rollback points before significant changes:

Change Type	Rollback Method	When
Single file edit	Git stash / undo	Before complex refactors
Multi-file change	Git branch	Before feature implementations
Configuration change	Backup file	Before env/config modifications
Database change	Migration rollback	Before schema changes

Progressive Enhancement

Build features incrementally, not all at once:

1. Static first — Get the HTML structure right
2. Styled second — Apply design tokens and layout
3. Interactive third — Add event handlers and state
4. Accessible fourth — Verify a11y (should be mostly done from patterns)
5. Optimized fifth — Performance tuning if needed

---

Human Approval Gates

These areas ALWAYS require human approval before proceeding:

Gate	Why	What to Present
Authentication	Security-critical	Full auth flow diagram
Data Models	Schema changes affect everything	ER diagram or schema diff
Payment Integration	Financial liability	Payment flow + error states
Infrastructure	Production impact	Change plan + rollback plan
Third-Party APIs	External dependencies	API contract + failure modes
User Data Handling	Privacy/legal	Data flow + retention policy

---

Design Tool Integration

Figma Import

When receiving Figma designs:

1. Extract design tokens (colors, spacing, typography)
2. Map to existing component patterns
3. Generate components using extracted tokens
4. Verify visual match (screenshot comparison if available)

Framer/Design Export

When exporting to design tools:

1. Export component API as design properties
2. Map state variants to design variants
3. Include accessibility annotations
4. Document interaction patterns

---

HALT CONDITIONS

STOP and ask the human when:

• Authentication or authorization logic needs changing
• Payment or billing code is involved
• User data schema is being modified
• Infrastructure or deployment configuration changes
• Third-party API contracts are being established
• The design intent from the original prompt is unclear
• Three consecutive generation attempts haven't met requirements
• Ethical review flags a potential dark pattern
• Performance budget would be exceeded
• Accessibility compliance cannot be met with current approach

---

Language Patterns

TypeScript

// AI-assisted development guard
function aiSafeOperation<T>(
  operation: () => T,
  rollback: () => void,
  riskLevel: 'low' | 'medium' | 'high'
): T {
  if (riskLevel === 'high') {
    throw new Error('HALT: High-risk operation requires human approval');
  }
  try {
    return operation();
  } catch (error) {
    rollback();
    throw error;
  }
}

Rust

/// AI-assisted development guard
enum RiskLevel {
    Low,
    Medium,
    High,
}

fn ai_safe_operation<T, F, R>(operation: F, rollback: R, risk: RiskLevel) -> Result<T, String>
where
    F: FnOnce() -> Result<T, String>,
    R: FnOnce(),
{
    if matches!(risk, RiskLevel::High) {
        return Err("HALT: High-risk operation requires human approval".into());
    }
    operation().map_err(|e| {
        rollback();
        e
    })
}

Go

// AISafeOperation guards AI-driven operations by risk level
func AISafeOperation[T any](operation func() (T, error), rollback func(), risk RiskLevel) (T, error) {
    var zero T
    if risk == RiskHigh {
        return zero, fmt.Errorf("HALT: High-risk operation requires human approval")
    }
    result, err := operation()
    if err != nil {
        rollback()
        return zero, err
    }
    return result, nil
}

---

RELATED DOCUMENTS

Document	Purpose
AGENT_GUARDRAILS.md	Core safety protocols (The Four Laws)
2026_GAME_DESIGN.md	Game design guardrails
2026_UI_UX_STANDARD.md	UI component patterns
ACCESSIBILITY_GUIDE.md	WCAG 3.0+ compliance
ETHICAL_ENGAGEMENT.md	Dark pattern prevention
STATE_MANAGEMENT.md	State architecture patterns
PROMPTING_GUIDE.md	Effective prompting for AI development