AI-Assisted Development Overview

Source index and context

RFC 2119 Key Words

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Guides in This Section

Guide	Covers
ai-workflows.md	Hero Flow, TDD/3-way compare, visual iteration, long-running tasks
claude.md	Anthropic Claude: model selection, API patterns, extended thinking
claude-code.md	Claude Code CLI: hooks, permissions, subagents, commands, MCP
openai.md	OpenAI GPT and Codex: API patterns, structured output, cost control
gemini.md	Google Gemini: model selection, function calling, long context
local-llms.md	Self-hosted models: Ollama, vLLM, Docker Model Runner
agents-md.md	AGENTS.md project instruction files and tool compatibility
code-agents.md	Code agent family: review, performance, accessibility, API, tests
security-agents.md	Security agent family: threat modeling, compliance, detection
system-agents.md	System agent family: Docker, Ansible, Linux, networking, storage
release-manager-agent.md	Release automation, quality gates, changelog generation
security.md	LLM security: prompt injection, data handling, supply chain

Introduction
When to Use AI Assistance
Model Selection Guide
Provider Comparison
Model Recommendations by Task Type
Workflow Patterns
Context Management Strategies
Cost Optimization Patterns
Quality Assurance for AI Output
Team Adoption Strategies
References

Introduction

This guide provides comprehensive guidance on effectively integrating AI assistance into software development workflows. Organizations and individual developers MUST use this guide to establish consistent, efficient, and cost-effective AI-assisted development practices.

AI-assisted development tools have evolved rapidly, offering capabilities ranging from code completion to complex architectural analysis. This guide helps teams navigate the landscape of AI tools, select appropriate models for specific tasks, and implement workflows that maximize productivity while maintaining code quality.

Scope

This guide covers:

Strategic selection of AI models and providers
Tactical workflow patterns for different development tasks
Cost management and optimization strategies
Quality assurance practices for AI-generated content
Team adoption and scaling considerations

For provider-specific best practices, see the Claude/Anthropic guide¹.

Audience

This guide is intended for:

Software engineers using AI coding assistants
Engineering managers establishing team AI practices
DevOps engineers optimizing AI infrastructure
Technical leads evaluating AI tooling investments

When to Use AI Assistance

Task Types Suitable for AI Assistance

Teams MUST evaluate tasks against the following criteria before engaging AI assistance:

High-Value AI Tasks

AI assistance SHOULD be used for the following task types:

Boilerplate Code Generation
- CRUD operations
- API endpoint scaffolding
- Database model definitions
- Configuration file templates
- Test fixtures and mock data
Code Translation and Migration
- Language-to-language translation
- Framework migration (e.g., Class components to Hooks)
- API version upgrades
- Legacy code modernization
Documentation Generation
- Function and class docstrings
- API documentation
- README files
- Changelog generation from commits
- Architecture diagrams (via markup languages)
Test Generation
- Unit test scaffolding
- Edge case identification
- Test data generation
- Integration test templates
- Regression test creation
Code Review and Analysis
- Security vulnerability detection
- Performance bottleneck identification
- Code smell detection
- Complexity analysis
- Dependency impact assessment
Refactoring Assistance
- Extract method/class refactoring
- Rename refactoring across files
- Pattern implementation (e.g., applying Strategy pattern)
- Dead code identification
- Duplicate code detection
Problem Solving and Debugging
- Error message interpretation
- Stack trace analysis
- Algorithm optimization suggestions
- Third-party library usage examples
- Configuration troubleshooting

Medium-Value AI Tasks

AI assistance MAY be used for these tasks with appropriate oversight:

Architecture Design
- System design exploration
- Trade-off analysis
- Pattern recommendations
- Scalability planning
Complex Algorithm Implementation
- Search and sort algorithms
- Graph algorithms
- Optimization problems
- Data structure implementation
Integration Code
- Third-party API integration
- Database query optimization
- Message queue patterns
- Caching strategies

Low-Value AI Tasks

AI assistance SHOULD NOT be the primary approach for:

Domain-Specific Business Logic
- Core business rules
- Complex state machines
- Financial calculations
- Regulatory compliance logic
Critical Security Components
- Authentication systems
- Authorization logic
- Cryptographic implementations
- Security-sensitive data handling
Performance-Critical Code
- Hot path optimizations
- Low-latency systems
- Real-time processing
- Hardware-specific optimizations

Complexity Level Guidelines

Simple Tasks (< 100 LOC, < 30 minutes)

MUST use AI for initial generation
SHOULD use faster, cheaper models
MAY skip detailed code review for non-critical paths
Examples: utility functions, simple data transformations, basic CRUD

Moderate Tasks (100-500 LOC, 30 minutes - 4 hours)

SHOULD use AI for scaffolding and structure
MUST conduct thorough code review
SHOULD iterate with AI on refinements
Examples: feature implementation, service integration, component development

Complex Tasks (500+ LOC, > 4 hours)

SHOULD use AI for exploration and planning phases
MUST break down into smaller sub-tasks
MUST have senior review of AI-generated architecture
SHOULD use multiple AI interactions with context refinement
Examples: new service creation, major refactoring, architectural changes

Decision Tree: Should I Use AI for This Task?

Is the task well-defined with clear requirements?
├─ YES: Continue
└─ NO: Define requirements first, then consider AI

Is similar code already in the codebase?
├─ YES: Use AI with codebase context
└─ NO: Continue

Does the task involve critical security/business logic?
├─ YES: Use AI for exploration only, implement manually
└─ NO: Continue

Is the expected output > 500 LOC?
├─ YES: Break into smaller tasks, use AI for each
└─ NO: Continue

Is this a well-known pattern or common task?
├─ YES: Use AI with high confidence
└─ NO: Use AI with extensive validation

Does your team have expertise to validate the output?
├─ YES: Proceed with AI assistance
└─ NO: Use AI for learning, but seek expert review

Model Selection Guide

Capability vs Cost Matrix

The following matrix MUST be used as a reference for model selection decisions:

Capability Level vs Cost (per 1M tokens)

High Capability, High Cost ($10-30/1M input)
┌─────────────────────────────────────────┐
│ - Claude Opus 4.5[^2]                   │
│ - GPT-4 Turbo[^3]                       │
│                                         │
│ Use for: Complex reasoning, architecture│
│ decisions, security analysis            │
└─────────────────────────────────────────┘

High Capability, Medium Cost ($3-10/1M input)
┌─────────────────────────────────────────┐
│ - Claude Sonnet 4.5[^2]                 │
│ - GPT-4o[^3]                            │
│                                         │
│ Use for: Most coding tasks, reviews,   │
│ complex refactoring                     │
└─────────────────────────────────────────┘

Medium Capability, Low Cost ($0.10-3/1M input)
┌─────────────────────────────────────────┐
│ - Claude Haiku 4.5[^2]                  │
│ - GPT-4o mini[^3]                       │
│                                         │
│ Use for: Code completion, simple tasks, │
│ documentation generation                │
└─────────────────────────────────────────┘

Gemini Tiers (input price per 1M tokens, verified 2026-09)[^4]
┌─────────────────────────────────────────┐
│ - Gemini 2.5 Pro: $1.25/1M input        │
│ - Gemini 3.8 Flash: $0.75/1M input      │
│ - Gemini 3.5 Flash-Lite: $0.30/1M input │
│                                         │
│ Use for: 1M-token context, high-volume  │
│ agentic work, cost-sensitive coding     │
└─────────────────────────────────────────┘

Specialized Models (Variable Cost)
┌─────────────────────────────────────────┐
│ - Codex variants[^3]                    │
│ - CodeLlama[^5]                         │
│ - StarCoder[^6]                         │
│ - Self-hosted models                    │
│                                         │
│ Use for: High-volume tasks, privacy     │
│ requirements, custom fine-tuning        │
└─────────────────────────────────────────┘

Model Characteristics Reference

Teams MUST consider the following characteristics when selecting models:

Characteristic	Opus/GPT-4 Class	Sonnet/GPT-4o Class	Haiku/Mini Class	Self-Hosted
Context Window	128K-200K tokens	128K-200K tokens	128K-200K tokens	4K-32K tokens
Response Speed	Slower (3-10s)	Medium (1-5s)	Fast (<1s)	Variable
Code Quality	Excellent	Very Good	Good	Variable
Reasoning Depth	Deep	Moderate-Deep	Basic	Variable
Cost per 1M input	$10-30	$3-10	$0.10-3	Hardware cost
Cost per 1M output	$30-90	$10-30	$0.30-10	Hardware cost
Best For	Architecture, security	General development	Autocomplete, docs	Privacy, volume

Selection Criteria

When to Use Premium Models (Opus, GPT-4)

Teams MUST use premium models when:

High-Stakes Decisions
- Architectural choices affecting multiple teams
- Security-sensitive code review
- Performance-critical algorithm design
- Database schema design for core systems
Complex Reasoning Required
- Multi-step refactoring across many files
- Debugging complex race conditions
- Analyzing intricate business logic
- Evaluating multiple solution approaches
Quality Over Speed Priority
- Production code generation
- Customer-facing feature implementation
- Critical path optimization
- Regulatory compliance code

When to Use Mid-Tier Models (Sonnet, GPT-4o)

Teams SHOULD use mid-tier models for:

Standard Development Tasks
- Feature implementation
- Bug fixes
- Code reviews
- Test generation
- API integration
Balanced Requirements
- Good quality needed but not critical
- Moderate complexity
- Regular development velocity
- Standard refactoring tasks
Most Daily Development Work
- This SHOULD be the default choice for 70-80% of AI-assisted tasks

When to Use Budget Models (Haiku, GPT-4o mini)

Teams MAY use budget models for:

High-Volume, Low-Complexity Tasks
- Code completion suggestions
- Simple documentation generation
- Formatting and style fixes
- Straightforward CRUD operations
Exploratory Work
- Initial code sketches
- Brainstorming session notes
- Quick prototypes
- Learning exercises
Non-Critical Paths
- Internal tooling
- Script automation
- Development utilities
- Test data generation

When to Use Self-Hosted Models

Organizations SHOULD consider self-hosted models when:

Privacy Requirements
- Proprietary code must not leave infrastructure
- Regulatory compliance prohibits external AI services
- Intellectual property concerns
- Customer data confidentiality
Cost at Scale
- Token usage exceeds 100M tokens/month
- Predictable high-volume usage
- Long-term cost optimization
- Budget constraints with high usage
Customization Needs
- Domain-specific fine-tuning required
- Internal coding standards enforcement
- Custom tooling integration
- Specialized language or framework focus

Provider Comparison

Comprehensive Provider Analysis

Organizations MUST evaluate providers based on the following detailed comparison:

Feature	Anthropic Claude²	OpenAI GPT³	Google Gemini⁴	Self-Hosted (Llama/CodeLlama)⁵⁶
Latest Models	Opus 4.5, Sonnet 4.5, Haiku 4.5	GPT-4 Turbo, GPT-4o, GPT-4o mini	Gemini 2.5 Pro, 3.8 Flash, 3.5 Flash-Lite	Llama 3.1, CodeLlama 34B, StarCoder2
Context Window	200K tokens	128K tokens	1M tokens (2.5 Pro, 3.8 Flash)	4K-128K depending on model
Coding Strength	Excellent (especially Sonnet/Opus)	Excellent	Very Good	Good (code-specific models)
Response Speed	Fast (Sonnet/Haiku), Slower (Opus)	Fast (GPT-4o), Medium (GPT-4)	Fast (Flash), Medium (Pro)	Variable (depends on hardware)
API Reliability	Excellent (99.9% uptime)	Excellent (99.9% uptime)	Very Good (99.5% uptime)	Depends on infrastructure
Pricing Model	Token-based, clear tiers	Token-based, clear tiers	Token-based, generous free tier	Hardware + operational costs
Privacy/Data Use	Not used for training	Not used for training (API)	Paid Services: not used to improve Google products. Unpaid Services: used to improve Google products, human review possible⁷	Complete control
Tool/Function Calling	Excellent	Excellent	Good	Limited (depends on model)
Structured Output	Good (via prompting)	Excellent (JSON mode)	Good	Limited
System Prompts	Excellent support	Good support	Good support	Variable
Rate Limits	Tier-based (generous)	Tier-based	Generous (especially free tier)	Hardware-limited
Regional Availability	Global (some restrictions)	Global (some restrictions)	Limited (expanding)	No restrictions
Enterprise Features	Available	Comprehensive	Growing	Full control
Compliance	SOC2, GDPR, HIPAA available	SOC2, GDPR, HIPAA available	SOC2, GDPR	Self-managed
Support Quality	Excellent (email, docs)	Excellent (email, docs, forum)	Good (docs, community)	Community-based
Integration Ecosystem	Growing rapidly	Extensive	Growing	Depends on implementation
Multimodal	Yes (images in, text out)	Yes (images, audio, text)	Yes (comprehensive)	Limited
Code Execution	No (tool use)	Limited	Limited	Can be implemented
Best Use Case	Thoughtful coding, complex reasoning	General purpose, established ecosystem	Long context, cost-conscious	Privacy, customization, volume

Provider-Specific Strengths

Anthropic Claude

Claude SHOULD be selected when:

Code Quality Priority: Claude Sonnet 4.5 and Opus 4.5 excel at producing clean, idiomatic code
Safety and Reasoning: Superior at considering edge cases and security implications
Long-form Analysis: Extended code review and architectural analysis
Context Understanding: Excellent at maintaining context across long conversations
Tool Use: Superior function calling and tool integration capabilities

Pricing (as of 2025)⁸:

Opus 4.5: $15/1M input tokens, $75/1M output tokens
Sonnet 4.5: $3/1M input tokens, $15/1M output tokens
Haiku 4.5 (claude-haiku-4-5-20251001): $1/1M input tokens, $5/1M output tokens⁹

Retired budget model: claude-3-5-haiku-20241022 (Claude Haiku 3.5) was deprecated on 19 December 2025 and retired on 19 February 2026; requests to a retired model fail¹⁰. claude-haiku-4-5-20251001 is Anthropic’s named replacement and offers a 200K-token context window with a 64K-token maximum output⁹. Teams migrating MUST re-run their own evaluations rather than swapping the identifier in place, because output limits, pricing, and thinking behavior differ between the two models.

Why: Retirement dates on Anthropic’s deprecation page apply to Anthropic-operated platforms (the Claude API, Claude Platform on AWS, and Microsoft Foundry). Partner-operated platforms — Amazon Bedrock and Google Cloud — set their own schedules, so a model that still answers on Bedrock can already be dead on the Claude API¹⁰. Teams MUST check the lifecycle table for the platform they actually call.

Rate Limits¹¹: Scale 1 tier starts at 50K requests/day, Scale 2 at 1M requests/day

OpenAI GPT

GPT SHOULD be selected when:

Established Ecosystem: Extensive library of tools, plugins, and integrations
Structured Output: JSON mode and function calling are critical requirements
Multimodal Needs: Vision, audio, and text processing in one model
Broad Capability: General-purpose tasks beyond coding
Community Resources: Largest community with extensive examples and patterns

Pricing (as of 2025)¹²:

GPT-4 Turbo: $10/1M input tokens, $30/1M output tokens
GPT-4o: $5/1M input tokens, $15/1M output tokens
GPT-4o mini: $0.15/1M input tokens, $0.60/1M output tokens

Rate Limits¹³: Tier-based from 500 requests/day (free) to millions (enterprise)

Google Gemini

Gemini SHOULD be selected when:

Long Context: Tasks requiring 1M+ token context windows
Cost Optimization: Flash and Flash-Lite tiers for high-volume paid workloads
Google Ecosystem: Integration with Google Cloud services
Multimodal Tasks: Vision and document understanding
Rapid Iteration: Fast Flash models for quick feedback loops

Current model IDs⁴: gemini-2.5-pro (Pro tier), gemini-3.8-flash (Flash tier), gemini-3.5-flash-lite (budget tier). Google publishes no shutdown date for any of the three¹⁴.

Pricing (paid tier, Standard service tier, verified 2026-09-08)¹⁵:

Gemini 2.5 Pro: $1.25/1M input tokens and $10/1M output tokens for prompts of 200K tokens or fewer; $2.50/1M input and $15/1M output above 200K
Gemini 3.8 Flash: $0.75/1M input tokens and $3.75/1M output tokens through 31 December 2026, rising to $1.50/1M input and $7.50/1M output on 1 January 2027
Gemini 3.5 Flash-Lite: $0.30/1M input tokens, $2.50/1M output tokens

Migration from Gemini 1.5: gemini-1.5-pro, gemini-1.5-flash, and gemini-1.5-flash-8b are shut down; they no longer appear in the model catalog or the deprecation schedule, and their endpoints are gone⁴¹⁴. Teams MUST re-test the application, not just swap the identifier: on Gemini 3 and later the API replaces thinking_budget with a thinking_level enum, rejects temperature, top_p, top_k, and candidate_count, and tightens turn-validation and function-calling rules¹⁶. Prompt behavior, output limits, and cost forecasts all need re-baselining against the replacement.

Why: A shut-down endpoint fails closed. Code still naming a 1.5 model returns an error rather than a worse answer, so every guide recommendation pointing at 1.5 is an outage waiting for the next deployment.

Data use — decide before sending code⁷: Google’s Gemini API Additional Terms of Service split behavior by contractual service status, not by whether a given request happens to cost money.

Service status	How Google uses prompts and responses
Unpaid Services — Google AI Studio used without an active billing link, and unpaid Gemini API quota	Content and generated responses are used to provide, improve, and develop Google products, services, and machine-learning technologies; human reviewers may read, annotate, and process input and output
Paid Services — AI Studio accessed from an account with a Cloud project on an active Cloud Billing account or a Workspace enterprise account, and Gemini API called through a Cloud project with active billing	Prompts and responses are not used to improve Google products; they are processed under Google’s data processor terms and logged only briefly, for abuse detection and legal obligations

Teams MUST therefore:

Classify the data first. Proprietary source code, customer data, credentials, and personal data MUST NOT be sent to Unpaid Services. The terms state it directly: “Do not submit sensitive, confidential, or personal information to the Unpaid Services.”
Confirm Paid Service status, do not infer it from the bill. Free-of-charge AI Studio access still counts as a Paid Service when the account carries active Cloud billing or enterprise Workspace access, and Gemini API usage counts as Paid only when the call goes through a Cloud project with an active billing account.
Apply the regional rule. For the European Economic Area, Switzerland, and the United Kingdom, the Paid Services data terms apply to all Services including unpaid quota, and API clients made available to users in those regions MUST use Paid Services only.

Why: Disclosure is irreversible. Once proprietary code has been submitted to an Unpaid Service, it has been licensed for product improvement and may already have been read by a human reviewer; no later upgrade to a paid tier undoes that. Provider choice therefore MUST follow the data classification, not the budget.

Rate Limits¹⁵: 2M tokens/minute on free tier, higher for paid

Self-Hosted Solutions

Self-hosted models MUST be considered when:

Data Privacy: Absolute requirement that code never leaves infrastructure
Cost at Scale: Processing 500M+ tokens/month
Customization: Fine-tuning on proprietary codebase required
Control: Need for complete control over model behavior and updates
Compliance: Regulatory requirements prevent external AI services

Popular Options:

Meta Llama 3.1 (70B/405B)⁵
- General purpose, good coding capability
- Requires significant GPU resources (A100 or H100)
- Inference cost: ~$0.10-0.50/1M tokens depending on infrastructure
CodeLlama 34B⁵
- Code-specialized variant of Llama
- Lower resource requirements than Llama 3.1 405B
- Good for code completion and generation
StarCoder2⁶
- Trained specifically on code
- Efficient for code completion tasks
- Available in 3B, 7B, 15B variants
DeepSeek Coder¹⁷
- Excellent code generation capability
- Competitive with GPT-4 on coding tasks
- Available in 1.3B to 33B sizes

Infrastructure Considerations:

MUST have GPU resources (minimum 1x A100 for 34B models)
SHOULD implement caching and batching for efficiency
MUST have robust monitoring and fallback strategies
SHOULD plan for model update and maintenance cycles

Model Recommendations by Task Type

Coding Tasks

Feature Implementation

Primary Recommendation: Claude Sonnet 4.5 or GPT-4o

These models SHOULD be used because:

Balanced cost-to-quality ratio
Fast enough for iterative development
Good at understanding requirements and context
Produce production-quality code

Example Workflow:

1. Describe feature requirements to AI
2. Request implementation with tests
3. Review and iterate on design
4. Request specific refinements
5. Final human review before merge

Estimated Cost: $0.05-0.20 per feature (moderate complexity)

Bug Fixing

Primary Recommendation: Claude Sonnet 4.5 or GPT-4o Budget Alternative: Claude Haiku 4.5 or GPT-4o mini (for simple bugs)

Bug fixing workflow SHOULD:

Provide error message and stack trace
Include relevant code context (50-200 lines)
Request explanation before fix
Review AI’s understanding
Request fix with test case

Example Prompt Structure:

I'm getting this error: [error message]

Stack trace:
[stack trace]

Here's the relevant code:
[code snippet]

Please:
1. Explain what's causing this error
2. Suggest a fix
3. Provide a test case to prevent regression

Estimated Cost: $0.01-0.05 per bug fix

Refactoring

Primary Recommendation: Claude Opus 4.5 or GPT-4 Turbo (complex), Sonnet/GPT-4o (standard)

Large refactoring tasks MUST:

Use premium models for planning phase
Break down into smaller chunks
Validate each step before proceeding
Include comprehensive test coverage

Refactoring Workflow:

Phase 1 (Opus/GPT-4): Analysis and Planning
- Analyze current structure
- Identify problems and code smells
- Propose refactoring approach
- Estimate impact and risk

Phase 2 (Sonnet/GPT-4o): Incremental Changes
- Implement step 1 with tests
- Validate and commit
- Implement step 2 with tests
- Validate and commit
- Continue until complete

Phase 3 (Sonnet/GPT-4o): Cleanup
- Remove dead code
- Update documentation
- Final integration tests

Estimated Cost: $0.50-5.00 for major refactoring

Code Generation (Boilerplate)

Primary Recommendation: Claude Haiku 4.5 or GPT-4o mini High-Volume Alternative: Self-hosted CodeLlama

Boilerplate generation SHOULD use budget models because:

Tasks are well-defined and simple
Cost savings are significant at scale
Quality is sufficient for standard patterns
Fast response time improves developer experience

Common Boilerplate Tasks:

CRUD endpoints
Database models
API clients
Configuration files
DTO/Entity mappings
Test fixtures

Estimated Cost: $0.008-0.04 per generation

Code Review Tasks

Security Review

Primary Recommendation: Claude Opus 4.5 or GPT-4 Turbo MUST NOT: Use budget models for security-sensitive reviews

Security review workflow MUST:

Use premium models exclusively
Request specific vulnerability categories
Include threat model context
Validate findings with security team
Never auto-merge based on AI approval alone

Review Prompt Template:

Please perform a security review of this code:

[code]

Specifically check for:
1. SQL injection vulnerabilities
2. XSS vulnerabilities
3. Authentication/authorization issues
4. Sensitive data exposure
5. CSRF vulnerabilities
6. Insecure dependencies
7. Cryptographic weaknesses
8. Input validation gaps

For each finding, provide:
- Severity (Critical/High/Medium/Low)
- Explanation
- Specific code location
- Remediation steps

Estimated Cost: $0.10-0.50 per review (depending on codebase size)

General Code Review

Primary Recommendation: Claude Sonnet 4.5 or GPT-4o

Standard code reviews SHOULD check:

Code style and conventions
Logic errors
Edge cases
Performance concerns
Test coverage
Documentation completeness

Review Workflow:

1. Submit PR diff to AI
2. Provide coding standards/guidelines
3. Request structured review
4. Address findings
5. Human reviewer validates AI feedback
6. Merge after both AI and human approval

Estimated Cost: $0.03-0.15 per PR

Performance Review

Primary Recommendation: Claude Opus 4.5 or GPT-4 Turbo (critical paths), Sonnet/GPT-4o (general)

Performance review SHOULD:

Include performance requirements (latency, throughput)
Provide profiling data if available
Request specific optimization suggestions
Consider algorithmic complexity
Evaluate database query efficiency

Estimated Cost: $0.05-0.30 per review

Documentation Tasks

API Documentation

Primary Recommendation: Claude Sonnet 4.5 or GPT-4o Budget Alternative: Claude Haiku 4.5 (for simple endpoints)

API documentation generation SHOULD:

Include code context
Request OpenAPI/Swagger format
Generate examples for each endpoint
Include error cases
Document authentication/authorization

Example Workflow:

Input: API endpoint code
Output:
- Endpoint description
- Parameters (path, query, body)
- Request/response examples
- Error codes and meanings
- Authentication requirements
- Rate limiting information

Estimated Cost: $0.02-0.08 per endpoint

Code Documentation (Docstrings)

Primary Recommendation: Claude Haiku 4.5 or GPT-4o mini

Docstring generation SHOULD:

Use budget models (simple, repetitive task)
Follow language-specific conventions
Include parameter types
Document exceptions/errors
Provide usage examples for public APIs

Batch Processing Approach:

Process multiple functions in single request:
- Submit 10-20 functions at once
- Request consistent format
- Review and commit in batches
- Significant cost savings vs. per-function

Estimated Cost: $0.004-0.02 per function

Architecture Documentation

Primary Recommendation: Claude Opus 4.5 or GPT-4 Turbo

Architecture documentation MUST:

Use premium models for accuracy
Include comprehensive codebase context
Generate diagrams (via Mermaid, PlantUML)
Document design decisions
Explain trade-offs

Documentation Workflow:

Phase 1: Analysis
- Analyze codebase structure
- Identify main components
- Map dependencies
- Understand data flow

Phase 2: Generation
- Write architecture overview
- Create system diagrams
- Document component interactions
- Explain design patterns used

Phase 3: Validation
- Review with architecture team
- Update based on feedback
- Maintain as living document

Estimated Cost: $0.50-3.00 per major documentation effort

README and Guides

Primary Recommendation: Claude Sonnet 4.5 or GPT-4o

README generation SHOULD include:

Project overview
Installation instructions
Quick start guide
Configuration options
Usage examples
Contributing guidelines
License information

Estimated Cost: $0.05-0.20 per README

Testing Tasks

Unit Test Generation

Primary Recommendation: Claude Sonnet 4.5 or GPT-4o Budget Alternative: Claude Haiku 4.5 (for simple functions)

Unit test generation SHOULD:

Cover happy path
Include edge cases
Test error conditions
Follow existing test patterns
Use appropriate assertions

Test Generation Prompt:

Generate unit tests for this function:

[function code]

Requirements:
- Use [testing framework]
- Test happy path
- Test edge cases: [list specific cases]
- Test error conditions
- Achieve >90% code coverage
- Follow existing test patterns in: [example test file]

Estimated Cost: $0.02-0.10 per test suite

Integration Test Generation

Primary Recommendation: Claude Sonnet 4.5 or GPT-4o

Integration tests SHOULD:

Use real or realistic test doubles
Cover main user flows
Include setup and teardown
Test component interactions
Validate data consistency

Estimated Cost: $0.05-0.25 per integration test

Test Data Generation

Primary Recommendation: Claude Haiku 4.5 or GPT-4o mini High-Volume Alternative: Self-hosted model

Test data generation SHOULD:

Use budget models (cost-effective for high volume)
Include realistic variations
Cover boundary conditions
Respect data constraints
Generate large datasets efficiently

Example Use Cases:

Mock API responses
Database seed data
User profiles
Transaction records
Event streams

Estimated Cost: $0.004-0.04 per dataset

End-to-End Test Generation

Primary Recommendation: Claude Sonnet 4.5 or GPT-4o

E2E tests SHOULD:

Cover critical user journeys
Include realistic scenarios
Handle async operations
Include proper wait conditions
Validate UI and data state

Estimated Cost: $0.10-0.40 per E2E test scenario

Workflow Patterns

Explore-Plan-Code-Commit Pattern

This workflow pattern SHOULD be the default approach for medium to complex tasks.

Phase 1: Explore (Model: Opus/GPT-4 or Sonnet/GPT-4o)

Objective: Understand the problem space and existing codebase

Steps:

Describe the task to AI
Ask AI to analyze relevant existing code
Request potential approaches
Discuss trade-offs
Identify potential challenges

Example Session:

Developer: I need to add rate limiting to our API. Here's our current
middleware structure: [code]. What approaches should I consider?

AI: [Analysis of existing code]
[Presents 3 approaches with trade-offs]
[Identifies integration points]
[Highlights potential issues]

Developer: Approach 2 looks good. What about distributed rate limiting
across multiple servers?

AI: [Discusses Redis-based approach]
[Provides implementation considerations]
[Suggests libraries]

Time Investment: 10-30 minutes Cost: $0.05-0.30 Value: Prevents costly mistakes, considers more alternatives

Phase 2: Plan (Model: Opus/GPT-4 or Sonnet/GPT-4o)

Objective: Create detailed implementation plan

Steps:

Break down task into subtasks
Identify files to modify
Determine test strategy
Plan commit strategy
Estimate effort

Example Output:

Implementation Plan: API Rate Limiting

Subtasks:
1. Add Redis dependency and configuration
2. Create RateLimitMiddleware class
3. Implement token bucket algorithm
4. Add rate limit headers to responses
5. Create integration tests
6. Update API documentation
7. Add monitoring/logging

Files to Modify:
- src/middleware/index.ts (add middleware)
- src/config/redis.ts (new file)
- src/types/middleware.ts (add types)
- tests/integration/rateLimit.test.ts (new file)
- docs/api.md (update)

Test Strategy:
- Unit tests for token bucket logic
- Integration tests for middleware behavior
- Load tests for performance validation

Commits:
1. Add Redis configuration
2. Implement rate limit middleware
3. Add tests
4. Update documentation

Estimated Effort: 4-6 hours

Time Investment: 10-20 minutes Cost: $0.03-0.15 Value: Clear roadmap, better estimates, fewer iterations

Phase 3: Code (Model: Sonnet/GPT-4o or Haiku/mini)

Objective: Implement planned changes

Steps:

Implement subtasks in order
Generate code for each subtask
Review and refine each piece
Run tests continuously
Iterate based on failures

Implementation Approach:

For each subtask:
1. Request implementation from AI
2. Review generated code
3. Request modifications if needed
4. Run tests locally
5. Fix any issues
6. Move to next subtask

Model Selection:

Complex logic: Sonnet/GPT-4o
Boilerplate: Haiku/mini
Critical sections: Opus/GPT-4

Time Investment: Varies by task size Cost: $0.10-2.00 for moderate features Value: Faster implementation, fewer bugs

Phase 4: Commit (Model: Haiku/mini for messages)

Objective: Create clean, reviewable commits

Steps:

Review all changes
Group related changes
Generate commit messages
Create PR description
Request review

Commit Message Generation:

Developer: Generate a commit message for these changes: [diff]

AI:
feat: Add Redis-based rate limiting middleware

- Implement token bucket algorithm for rate limiting
- Add configurable limits per endpoint
- Include rate limit headers in responses
- Add integration tests for rate limit behavior

This allows us to protect the API from abuse while providing
clear feedback to clients about their rate limit status.

Time Investment: 5-10 minutes Cost: $0.01-0.05 Value: Better commit history, clearer communication

TDD with AI Pattern

Test-Driven Development with AI assistance SHOULD follow this workflow:

Step 1: Generate Test Cases (Model: Sonnet/GPT-4o)

Process:

Developer: I need to implement a function that validates email addresses.
Generate comprehensive test cases.

AI: [Provides test cases]
- Valid standard email
- Valid email with subdomain
- Valid email with plus addressing
- Invalid: no @ symbol
- Invalid: multiple @ symbols
- Invalid: no domain
- Invalid: invalid domain format
- Invalid: no TLD
- Invalid: spaces in email
- Edge case: very long email
- Edge case: international characters

Output: List of test cases covering happy path, edge cases, and error conditions

Step 2: Write Tests First (Model: Sonnet/GPT-4o or Haiku/mini)

Process:

Developer: Write tests for these cases using Jest:
[List of test cases]

AI: [Generates test code]

describe('validateEmail', () => {
  it('should accept valid standard email', () => {
    expect(validateEmail('user@example.com')).toBe(true);
  });

  it('should accept valid email with subdomain', () => {
    expect(validateEmail('user@mail.example.com')).toBe(true);
  });

  // ... more tests

  it('should reject email with no @ symbol', () => {
    expect(validateEmail('userexample.com')).toBe(false);
  });

  // ... more tests
});

Validation: Developer MUST review tests before proceeding

Step 3: Implement to Pass Tests (Model: Sonnet/GPT-4o)

Process:

Developer: Implement validateEmail function to pass these tests:
[Test code]

AI: [Generates implementation]

function validateEmail(email: string): boolean {
  // Implementation that passes all tests
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

  if (!email || typeof email !== 'string') {
    return false;
  }

  // Additional validation logic

  return emailRegex.test(email);
}

Step 4: Refactor (Model: Sonnet/GPT-4o)

Process:

Developer: The function works but is hard to read. Refactor for clarity
while keeping all tests passing.

AI: [Provides refactored version]

function validateEmail(email: string): boolean {
  if (!isString(email)) return false;
  if (hasWhitespace(email)) return false;
  if (!hasAtSymbol(email)) return false;
  if (hasMultipleAtSymbols(email)) return false;
  if (!hasValidDomain(email)) return false;

  return true;
}

// Helper functions with clear purposes
function isString(value: any): boolean { ... }
function hasWhitespace(str: string): boolean { ... }
// ... etc

Benefits of TDD with AI:

AI excels at generating comprehensive test cases
Tests serve as specification for AI implementation
Reduces debugging time
Ensures edge cases are covered
Produces more maintainable code

Pair Programming with AI Pattern

This pattern treats AI as a pair programming partner for real-time development.

Continuous Collaboration Mode

Setup:

Keep AI session open during development
Share context continuously
Get instant feedback
Iterate rapidly

Example Session:

Developer: I'm starting work on user authentication. Here's the user model:
[code]

AI: I see you have username and passwordHash fields. For authentication,
you'll want to consider:
1. Password validation rules
2. Rate limiting on login attempts
3. Session management
4. Password reset flow

Would you like to start with the login endpoint or password validation?

Developer: Let's start with password validation. Company policy requires
8+ characters, one uppercase, one number, one special character.

AI: Here's a password validation function:
[code]

Developer: Good, but I need it to return specific error messages for each
requirement that fails.

AI: Updated version with detailed error messages:
[code]

Developer: Perfect. Now let's do the login endpoint.

[Continues...]

Benefits:

Immediate feedback
Course correction before investing time
Knowledge sharing
Faster problem resolution

Best Practices:

Share context upfront
Ask for explanations, not just code
Challenge AI suggestions
Maintain conversation history
Take breaks to review independently

Code Review with AI Pattern

AI-assisted code review SHOULD complement, not replace, human review.

Pre-Human Review Pattern

Workflow:

1. Developer completes implementation
2. Run AI code review first
3. Address AI feedback
4. Submit for human review
5. Human reviewer sees cleaner code

AI Review Prompt Template:

Please review this pull request:

Files changed:
[File 1]: [diff]
[File 2]: [diff]

Our coding standards:
- [Standard 1]
- [Standard 2]
- [Standard 3]

Please check for:
1. Code style violations
2. Potential bugs
3. Edge cases not handled
4. Performance issues
5. Security concerns
6. Test coverage gaps
7. Documentation completeness

Provide specific line numbers and suggestions.

AI Review Output Format:

## Critical Issues
- [File:Line] Security: SQL injection vulnerability in user input handling
- [File:Line] Bug: Potential null pointer exception when user is undefined

## Important Issues
- [File:Line] Performance: N+1 query problem in user data fetching
- [File:Line] Edge case: No validation for empty array input

## Suggestions
- [File:Line] Style: Consider extracting this logic to a separate function
- [File:Line] Readability: Complex conditional could be simplified

## Positive Observations
- Good test coverage (95%)
- Clear error messages
- Proper input validation

Benefits:

Catches obvious issues before human review
Frees human reviewers for higher-level concerns
Faster review cycles
More consistent standards enforcement

Parallel Review Pattern

Workflow:

1. Submit PR
2. Both AI and human review simultaneously
3. Compare findings
4. Address all unique issues from both
5. Learn from differences

Value: AI may catch mechanical issues while humans catch design issues

For complex implementations, iterative refinement SHOULD be used:

Iteration Cycle

Round 1: Basic Implementation

Model: Sonnet/GPT-4o
Goal: Working solution
Quality: Acceptable
Cost: Low

Round 2: Improvement

Model: Same or upgrade to Opus/GPT-4
Goal: Handle edge cases
Quality: Good
Cost: Medium

Round 3: Polish

Model: Opus/GPT-4 for critical, Sonnet/GPT-4o otherwise
Goal: Production-ready
Quality: Excellent
Cost: Higher

Example:

Round 1:
Developer: Implement a caching layer for API responses
AI: [Provides basic in-memory cache]
Result: Works but not production-ready

Round 2:
Developer: Update to handle cache expiration and memory limits
AI: [Adds TTL and LRU eviction]
Result: Better but needs distribution support

Round 3:
Developer: Make it work across multiple server instances using Redis
AI: [Implements distributed caching with Redis]
Result: Production-ready solution

Total cost: $0.15 vs $0.40 if started with premium model
Total time: 45 min vs potentially more with wrong initial approach

Context Management Strategies

Effective context management is CRITICAL for AI assistance quality. Poor context leads to:

Incorrect assumptions
Inappropriate solutions
Style inconsistencies
Integration problems

Context Window Optimization

Understanding Context Limits

Teams MUST understand and respect context window limits:

Model	Context Window	Practical Limit	Files (avg 500 lines)
Claude Opus/Sonnet	200K tokens	~150K tokens	~100-120 files
GPT-4 Turbo/4o	128K tokens	~100K tokens	~60-80 files
Gemini 2.5 Pro / 3.8 Flash	1M tokens	~800K tokens	~500-600 files
Budget models	128-200K tokens	~100K tokens	~60-80 files
Self-hosted	4-32K tokens	~3-25K tokens	~2-15 files

Note: Actual capacity varies based on code density and comment ratio

Prioritizing Context

When context limits are approached, prioritize in this order:

MUST Include (Priority 1):
- Current file being modified
- Direct dependencies
- Interface definitions
- Type definitions
- Configuration relevant to task
SHOULD Include (Priority 2):
- Similar existing implementations
- Test files for context
- Related utility functions
- Relevant documentation
MAY Include (Priority 3):
- Broader codebase structure
- Distantly related files
- Historical context
- General documentation

Context Assembly Strategies

File-Level Context

For Single-File Tasks:

Provide:
- Complete file content
- Import dependencies (interfaces/types)
- Related test file
- Relevant documentation

Example:
"""
I need to modify this function:

[complete file content]

Here are the type definitions it uses:
[type definitions]

Here's how it's currently tested:
[test file]

Task: [specific task]
"""

Estimated tokens: 2K-10K

Module-Level Context

For Feature Development:

Provide:
- Main files in module (3-5 files)
- Shared types/interfaces
- Module README or documentation
- Example usage

Structure:
"""
I'm working on the [module name] module.

Main files:
--- src/module/file1.ts ---
[content]

--- src/module/file2.ts ---
[content]

Shared types:
--- src/types/module.ts ---
[content]

Current usage example:
[example code]

Task: [specific task]
"""

Estimated tokens: 10K-30K

System-Level Context

For Architectural Tasks:

Provide:
- High-level architecture diagram (text/Mermaid)
- Key component interfaces
- Data flow description
- Integration points
- Critical constraints

Example:
"""
System architecture:
[Mermaid diagram or text description]

Key components:
1. [Component]: [brief description + interface]
2. [Component]: [brief description + interface]

Data flow:
[Sequence of operations]

Constraints:
- [Performance requirement]
- [Security requirement]
- [Scalability requirement]

Task: [architectural decision needed]
"""

Estimated tokens: 5K-20K

Context Caching Strategies

Some providers offer context caching to reduce costs and latency:

Claude Prompt Caching

Claude SHOULD use prompt caching when:

Reusing same codebase context across multiple requests
Iterating on implementation with stable context
Processing multiple related tasks

How it works:

First request: Full cost
Subsequent requests (within 5 minutes): 90% discount on cached portion
Automatically applies to prompts >1024 tokens

Example usage:

Request 1:
Context (cached): [10K tokens of codebase - costs full price]
Task: Implement feature A
Response: [implementation]

Request 2 (within 5 min):
Context (cached): [same 10K tokens - costs 10% of original]
Task: Now add tests for feature A
Response: [tests]

Request 3 (within 5 min):
Context (cached): [same 10K tokens - costs 10% of original]
Task: Update documentation
Response: [docs]

Cost savings: ~60% vs. non-cached

Best practices:

Structure prompts with stable context first
Make multiple related requests in succession
Batch related tasks together

OpenAI Context Management

GPT-4 does not offer automatic caching, but SHOULD:

Use conversation history efficiently
Reference previous responses rather than repeating
Break long sessions into focused conversations

Dynamic Context Selection

For large codebases, teams SHOULD implement dynamic context selection:

Similarity-Based Selection

Process:

Index codebase with embeddings
For each task, find most relevant files
Include top N most similar files
Add explicit dependencies

Tools:

code2vec for code embeddings
Vector databases (Pinecone, Weaviate)
Custom similarity scoring

Example:

Task: Add authentication to API endpoint

Similarity search finds:
1. existing-auth-middleware.ts (0.95 similarity)
2. user-service.ts (0.87 similarity)
3. auth-types.ts (0.85 similarity)
4. another-protected-endpoint.ts (0.78 similarity)

Include top 3 + explicit dependency (express types)

Dependency Graph Context

Process:

Build dependency graph of codebase
For target file, include:
- File itself
- Direct dependencies
- Dependents (who uses it)
- Shared utilities

Example:

Target: user-controller.ts

Dependency graph:
user-controller.ts
├── Dependencies:
│   ├── user-service.ts
│   ├── auth-middleware.ts
│   └── types/user.ts
└── Dependents:
    ├── routes/api.ts
    └── tests/user-controller.test.ts

Include all these files as context

Context Documentation Patterns

Teams SHOULD maintain context documentation to improve AI assistance:

Codebase Overview Document

Location: .ai/codebase-overview.md

Contents:

# Codebase Overview

## Architecture
[High-level architecture description]

## Directory Structure
- `/src/api` - REST API endpoints
- `/src/services` - Business logic
- `/src/models` - Data models
- `/src/utils` - Utility functions

## Key Technologies
- Framework: Express.js
- Database: PostgreSQL
- ORM: TypeORM
- Testing: Jest

## Coding Standards
- Style guide: Airbnb
- Naming: camelCase for variables, PascalCase for classes
- File structure: One class per file

## Common Patterns
- Service layer pattern for business logic
- Repository pattern for data access
- Dependency injection using tsyringe

Usage:

Include in context for new team members or AI:
"Here's our codebase overview: [content]
Now help me implement [feature]"

Decision Log

Location: .ai/decisions.md

Contents:

# Architecture Decision Log

## ADR-001: Use TypeORM for database access
Date: 2024-01-15
Status: Accepted

Context: Need ORM for PostgreSQL access
Decision: Use TypeORM
Alternatives considered: Prisma, Sequelize
Rationale: Team familiarity, TypeScript support

## ADR-002: Implement JWT-based authentication
Date: 2024-02-01
Status: Accepted

Context: Need stateless authentication
Decision: JWT with RS256 signing
Alternatives considered: Sessions, OAuth only
Rationale: Scalability, microservices compatibility

Usage: Helps AI understand why things are done certain ways

Multi-Turn Conversation Management

For complex tasks, maintain conversation continuity:

Conversation Structuring

Pattern:

Turn 1: Set context and explore
Turn 2: Plan approach
Turn 3: Implement part 1
Turn 4: Implement part 2
Turn 5: Integrate and test
Turn 6: Documentation

Benefits:

Build shared understanding
Leverage conversation memory
Avoid repeating context
Natural refinement process

Conversation Splitting

When to start new conversation:

Context has drifted from original task
Conversation becomes too long (>20 turns)
Switching to unrelated task
AI responses become inconsistent

Best practice: Summarize previous conversation when starting new one

Context Templates

Teams SHOULD create templates for common context scenarios:

Bug Fix Template

# Bug Fix Context

## Error Information
Error message: [error]
Stack trace: [trace]
Frequency: [how often]
Environment: [dev/staging/prod]

## Relevant Code
[affected files]

## Recent Changes
[recent commits to area]

## Expected vs Actual
Expected: [behavior]
Actual: [behavior]

## Steps to Reproduce
1. [step]
2. [step]

## Task
[what needs to be done]

Feature Implementation Template

# Feature Implementation Context

## Requirements
[user story or spec]

## Acceptance Criteria
- [ ] [criterion 1]
- [ ] [criterion 2]

## Relevant Existing Code
[similar features or related code]

## Technical Constraints
- [constraint 1]
- [constraint 2]

## Design Decisions Needed
- [decision 1]
- [decision 2]

## Task
[implementation request]

Cost Optimization Patterns

Managing AI costs is essential for sustainable adoption. Teams MUST implement cost optimization strategies.

Cost Monitoring

Establishing Baselines

Teams MUST track:

Cost per developer per month
Cost per task type
Cost per project phase
Token usage patterns

Example Metrics Dashboard:

Monthly AI Costs by Task Type:
- Code generation: $45 (12K requests)
- Code review: $30 (8K requests)
- Documentation: $15 (3K requests)
- Debugging: $25 (5K requests)
Total: $115/developer/month

Cost by Model:
- Opus/GPT-4: $35 (30% of cost, 5% of requests)
- Sonnet/GPT-4o: $60 (52% of cost, 60% of requests)
- Haiku/mini: $20 (18% of cost, 35% of requests)

Setting Budgets

Recommended approach:

Track costs for 1-2 months
Calculate average per developer
Set budget at 120% of average
Review monthly, adjust quarterly

Typical ranges (per developer per month):

Light usage: $20-50
Moderate usage: $50-150
Heavy usage: $150-400
Team leads/architects: $300-800

Model Tiering Strategy

Implement automatic model selection based on task characteristics:

Decision Matrix

Task Complexity: [Low | Medium | High]
Task Criticality: [Low | Medium | High]
Context Size: [Small | Medium | Large]
→ Model Selection

Examples:

Low complexity + Low criticality + Small context
→ Haiku/GPT-4o mini
Example: Simple docstring, basic CRUD

Medium complexity + Medium criticality + Medium context
→ Sonnet/GPT-4o
Example: Feature implementation, standard refactoring

High complexity + High criticality + Large context
→ Opus/GPT-4
Example: Architecture design, security review

Low complexity + High criticality + Small context
→ Sonnet/GPT-4o (not Opus - unnecessary cost)
Example: Fixing critical bug with clear cause

Automatic Routing

Implementation:

function selectModel(task: Task): Model {
  const complexity = assessComplexity(task);
  const criticality = assessCriticality(task);
  const contextSize = calculateContextSize(task);

  // High criticality always uses at least mid-tier
  if (criticality === 'high') {
    if (complexity === 'high') return Model.OPUS;
    return Model.SONNET;
  }

  // Low criticality can use budget models
  if (criticality === 'low') {
    if (complexity === 'low') return Model.HAIKU;
    if (complexity === 'medium') return Model.SONNET;
    return Model.SONNET; // Even high complexity, low criticality
  }

  // Medium criticality
  if (complexity === 'high') return Model.OPUS;
  if (complexity === 'medium') return Model.SONNET;
  return Model.HAIKU;
}

Batching Strategies

Batching multiple operations reduces per-request overhead:

Batch Processing Pattern

Instead of:

Request 1: Generate docstring for function A
Request 2: Generate docstring for function B
Request 3: Generate docstring for function C
Cost: 3 × overhead + 3 × generation cost

Do this:

Single Request: Generate docstrings for functions A, B, and C

Functions:
[Function A code]
[Function B code]
[Function C code]

Please generate docstrings for all three functions.

Cost: 1 × overhead + 1 × generation cost
Savings: ~60% vs individual requests

Optimal batch sizes:

Documentation: 10-20 items
Simple code generation: 5-10 items
Code review: 3-5 files
Refactoring: 2-3 related changes

Batch Timing

Schedule batch operations for:

Off-peak hours (lower rate limits hit)
End of day cleanup
Weekly documentation updates
Monthly codebase analysis

Caching Strategies

Response Caching

For deterministic tasks, cache AI responses:

Implementation:

interface CacheKey {
  taskType: string;
  codeHash: string;
  modelVersion: string;
}

async function getAIResponse(
  task: string,
  code: string
): Promise<string> {
  const key = createCacheKey(task, code);

  // Check cache first
  const cached = await cache.get(key);
  if (cached) {
    return cached;
  }

  // Call AI
  const response = await callAI(task, code);

  // Cache for future
  await cache.set(key, response, TTL_7_DAYS);

  return response;
}

Good candidates for caching:

Documentation generation (rarely changes)
Test generation (for stable code)
Code review of common patterns
Error explanations (same error = same explanation)

Poor candidates:

Exploratory conversations
Context-dependent tasks
Rapidly changing code
Personalized responses

Prompt Template Caching

Reuse prompt structures:

const templates = {
  codeReview: `Review this code for:
- Style issues
- Bugs
- Performance
- Security

Code:
{CODE}`,

  testGeneration: `Generate tests for:
{CODE}

Requirements:
- Use {FRAMEWORK}
- Cover edge cases
- Achieve >90% coverage`,
};

// Reuse template, just replace variables
const prompt = templates.codeReview.replace('{CODE}', actualCode);

Request Optimization

Token Reduction Techniques

Minify context without losing meaning:

Remove comments for AI context:

// Before: 1500 tokens
function calculateTotal(items: Item[]): number {
  // Sum up all item prices
  // Apply any discounts
  // Add tax if applicable
  return items.reduce((sum, item) => {
    // ... implementation
  }, 0);
}

// After: 800 tokens (same meaning for AI)
function calculateTotal(items: Item[]): number {
  return items.reduce((sum, item) => {
    // ... implementation
  }, 0);
}

Use file summaries for distant context:

// Instead of including full file:
--- services/user-service.ts (300 tokens) ---
[full file content]

// Use summary:
--- services/user-service.ts ---
// Handles user CRUD operations
// Key methods: createUser, getUser, updateUser, deleteUser
// Uses UserRepository for data access
// Includes validation and error handling

Selective imports:

// Don't include full dependency files
// Instead, include just the interface:

// From: (showing full implementation - 2000 tokens)
--- node_modules/@types/express/index.d.ts ---
[entire file]

// To: (just what's needed - 100 tokens)
--- Types from Express ---
interface Request { body: any; params: any; query: any; }
interface Response { json(data: any): void; status(code: number): Response; }

Streaming for Long Responses

Use streaming responses to:

Start processing sooner
Reduce perceived latency
Cancel early if direction is wrong
Provide progress feedback

async function generateWithStreaming(prompt: string) {
  const stream = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: prompt }],
    stream: true,
  });

  for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content || '';
    process.stdout.write(content); // Show immediately

    // Can cancel if output is going wrong direction
    if (shouldCancel(content)) {
      stream.controller.abort();
      break;
    }
  }
}

Cost-Aware Development Practices

Developer Education

Teams MUST educate developers on:

Cost per request for different models
How to choose appropriate models
Impact of context size on cost
Batching opportunities

Example training:

Cost Awareness 101:

1. Model costs (per 1M tokens input):
   - Haiku 4.5: $1 (cheapest)
   - Sonnet 4.5: $3 (3x more)
   - Opus 4.5: $15 (15x more)

2. Average request sizes:
   - Simple task: 1K-5K tokens
   - Medium task: 5K-20K tokens
   - Complex task: 20K-100K tokens

3. Quick math:
   - 100 simple tasks with Haiku: ~$0.12
   - 100 simple tasks with Opus: ~$1.80
   - Same output quality for simple tasks!

4. Rule of thumb:
   - Use cheapest model that produces acceptable results
   - Upgrade only when necessary
   - Batch similar operations
   - Monitor your personal usage

Usage Analytics

Provide developers with personal usage dashboards:

Your AI Usage This Month:

Requests: 847
Total tokens: 12.3M input, 3.1M output
Cost: $127.50

Breakdown by model:
- Opus: 23 requests (3%), $45.20 (35%)
- Sonnet: 512 requests (60%), $68.30 (54%)
- Haiku: 312 requests (37%), $14.00 (11%)

Recommendations:
- You used Opus for 8 documentation tasks - try Sonnet
- Good use of Haiku for code completion
- Average context size: 18K tokens - consider reducing

Free Tier Maximization

For teams with budget constraints:

Free tiers differ in how the provider treats what you send. Teams MUST read the data-use terms before a free tier touches a repository: Gemini’s Unpaid Services use submitted content and generated responses to improve Google products, and human reviewers may read that content⁷. See Google Gemini for the Unpaid/Paid split and the EEA, Switzerland, and UK exception.

Free Tier Limits (2025)

Provider	Free Tier	Limits	Data use
Claude	Limited trial	~50 requests/day on free	Verify in the provider’s current terms
OpenAI	$5 credit (new users)	Expires after 3 months	Verify in the provider’s current terms
Gemini	Generous free tier	60 requests/minute	Unpaid Services: used to improve Google products, human review possible⁷
Groq	Free tier available	Rate limited	Verify in the provider’s current terms

Strategy for Free Tiers

Use Gemini free tier for non-sensitive exploration only: throwaway snippets, public samples, and learning exercises. Proprietary, customer, or personal data MUST NOT be sent to an unpaid tier⁷.
Reserve paid tier for production: Use Claude/OpenAI for critical work, and use Gemini Paid Services for anything covered by a data classification.
Self-host for volume: Once usage exceeds free tiers significantly
Rotate accounts carefully: Check ToS, many prohibit multiple accounts

Why: A free tier that trains on your input converts a cost saving into an irreversible disclosure. The saving is measured in cents; the disclosure is permanent.

ROI Monitoring

Teams MUST track return on investment:

Metrics to Track

Time Savings:

Task: Implement authentication feature

Without AI:
- Research: 1 hour
- Implementation: 4 hours
- Testing: 1 hour
- Documentation: 0.5 hour
Total: 6.5 hours

With AI:
- Research (with AI): 0.5 hour
- Implementation (with AI): 2 hours
- Testing (with AI): 0.5 hour
- Documentation (with AI): 0.25 hour
Total: 3.25 hours

Time saved: 3.25 hours
AI cost: $2.50
Developer cost: $150/hour (loaded)
ROI: $487.50 saved / $2.50 cost = 195:1

Quality Improvements:

Bugs prevented (AI review caught)
Security issues identified
Test coverage increase
Documentation completeness

Velocity Improvement:

Story points per sprint before/after
Features delivered per quarter
Time to production

Quality Assurance for AI Output

AI-generated code MUST undergo rigorous quality assurance. Teams MUST NOT merge AI-generated code without validation.

Multi-Level Review Process

Level 1: Automated Validation (MUST)

All AI-generated code MUST pass:

Linting:

# Run linter
npm run lint

# Auto-fix where possible
npm run lint:fix

# Fail CI if lint errors remain

Type Checking:

# TypeScript
tsc --noEmit

# Python
mypy src/

# Go
go vet ./...

Unit Tests:

# Run existing tests
npm test

# Check coverage
npm run test:coverage

# Require minimum coverage (e.g., 80%)

Security Scanning:

# Dependency vulnerabilities
npm audit

# Static security analysis
semgrep --config=auto

# Secret detection
gitleaks detect

Formatting:

# Ensure consistent formatting
prettier --check .

# Auto-format
prettier --write .

CI Pipeline Example:

# .github/workflows/ai-code-validation.yml
name: AI Code Validation

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Lint
        run: npm run lint

      - name: Type Check
        run: npm run type-check

      - name: Test
        run: npm test

      - name: Security Scan
        run: npm audit && semgrep --config=auto

      - name: Format Check
        run: prettier --check .

Level 2: Code Review (MUST)

Human review MUST check:

Logic Correctness:
- Does it solve the actual problem?
- Are edge cases handled?
- Is error handling appropriate?
Integration:
- Does it fit with existing architecture?
- Are patterns consistent with codebase?
- Does it respect boundaries?
Performance:
- Are there obvious performance issues?
- Is complexity reasonable (O(n) vs O(n²))?
- Are resources properly managed?
Security:
- Input validation present?
- No injection vulnerabilities?
- Authentication/authorization correct?
- Sensitive data handled properly?
Maintainability:
- Is code readable?
- Are names meaningful?
- Is complexity justified?
- Is documentation sufficient?

Review Checklist:

## AI-Generated Code Review Checklist

### Correctness
- [ ] Solves the stated problem
- [ ] Handles edge cases
- [ ] Error handling is appropriate
- [ ] No logical errors

### Integration
- [ ] Follows existing patterns
- [ ] Consistent with codebase style
- [ ] Respects module boundaries
- [ ] Doesn't duplicate existing functionality

### Performance
- [ ] No obvious performance issues
- [ ] Appropriate data structures
- [ ] Efficient algorithms
- [ ] Resources properly cleaned up

### Security
- [ ] Input validation present
- [ ] No injection vulnerabilities
- [ ] Auth/authz correct
- [ ] No hardcoded secrets
- [ ] Sensitive data protected

### Maintainability
- [ ] Code is readable
- [ ] Names are meaningful
- [ ] Comments explain why, not what
- [ ] Complexity is justified
- [ ] Tests are comprehensive

### AI-Specific Checks
- [ ] Verified AI didn't hallucinate APIs
- [ ] Checked for common AI mistakes
- [ ] Validated assumptions made by AI
- [ ] Confirmed best practices followed

Level 3: Testing in Context (SHOULD)

Beyond unit tests, SHOULD verify:

Integration Tests:

// Test AI-generated component integrates correctly
describe('AI-generated UserAuth integration', () => {
  it('should integrate with existing auth flow', async () => {
    const result = await fullAuthenticationFlow();
    expect(result).toBeDefined();
  });

  it('should work with all user types', async () => {
    for (const userType of USER_TYPES) {
      const result = await authenticateUser(userType);
      expect(result.authenticated).toBe(true);
    }
  });
});

Manual Testing:
- Run feature locally
- Test happy path
- Try to break it
- Verify error messages
Performance Testing (for critical paths):

// Load test AI-generated endpoint
describe('Performance', () => {
  it('should handle 1000 req/s', async () => {
    const results = await loadTest({
      url: '/api/endpoint',
      requestsPerSecond: 1000,
      duration: 60,
    });

    expect(results.p95).toBeLessThan(100); // 95th percentile < 100ms
    expect(results.errorRate).toBeLessThan(0.01); // < 1% errors
  });
});

Common AI Mistakes to Watch For

Hallucinated APIs

Problem: AI invents functions or methods that don’t exist

Example:

// AI might generate:
import { validateEmail } from '@utils/validation';

// But @utils/validation doesn't export validateEmail

Detection:

Run type checking
Verify imports exist
Check API documentation

Prevention:

Provide actual API documentation in context
Include real import examples
Use AI with codebase knowledge

Outdated Patterns

Problem: AI uses deprecated or outdated approaches

Example:

// AI might generate React class component:
class UserProfile extends React.Component {
  constructor(props) {
    super(props);
    this.state = { user: null };
  }
  // ...
}

// When codebase uses hooks:
function UserProfile() {
  const [user, setUser] = useState(null);
  // ...
}

Detection:

Code review for outdated patterns
Linting rules for deprecated features
Compare with existing codebase

Prevention:

Specify framework version in prompt
Provide current pattern examples
Include recent code as context

Over-Engineering

Problem: AI creates unnecessarily complex solutions

Example:

// AI might generate full factory pattern for simple task:
interface UserFactory {
  createUser(type: string): User;
}

class ConcreteUserFactory implements UserFactory {
  createUser(type: string): User {
    // Complex factory logic
  }
}

// When simple function would suffice:
function createUser(type: string): User {
  return new User(type);
}

Detection:

Review complexity vs requirements
Check if simpler solution exists
Validate design patterns are necessary

Prevention:

Specify simple or minimal in prompts
Provide simple examples as templates
Request explanation of design choices

Security Oversights

Problem: AI misses security considerations

Example:

// AI might generate:
app.post('/api/user', (req, res) => {
  const user = req.body;
  db.query(`INSERT INTO users VALUES ('${user.name}', '${user.email}')`);
  // SQL injection vulnerability!
});

// Should be:
app.post('/api/user', (req, res) => {
  const { name, email } = validateUserInput(req.body);
  db.query('INSERT INTO users VALUES (?, ?)', [name, email]);
});

Detection:

Security scanning tools (Semgrep, Snyk)
Manual security review
Penetration testing

Prevention:

Explicitly request security considerations
Provide secure examples
Use security-focused prompts

Validation Checklists by Task Type

Feature Implementation Validation

## Feature Implementation Checklist

### Requirements
- [ ] Implements all acceptance criteria
- [ ] Handles specified edge cases
- [ ] Includes error scenarios

### Code Quality
- [ ] Passes linting
- [ ] Passes type checking
- [ ] Follows style guide
- [ ] No code smells

### Testing
- [ ] Unit tests present
- [ ] Integration tests present (if needed)
- [ ] All tests pass
- [ ] Coverage >80% of new code

### Security
- [ ] Input validation
- [ ] Output encoding
- [ ] Auth/authz checks
- [ ] No secrets in code

### Performance
- [ ] No N+1 queries
- [ ] Appropriate complexity
- [ ] Efficient data structures
- [ ] Resources cleaned up

### Documentation
- [ ] Code comments for complex logic
- [ ] API docs updated
- [ ] README updated (if needed)
- [ ] CHANGELOG updated

Refactoring Validation

## Refactoring Checklist

### Behavior Preservation
- [ ] All existing tests still pass
- [ ] No new test failures
- [ ] Manual testing confirms same behavior
- [ ] No breaking changes (or documented)

### Improvement Verification
- [ ] Complexity reduced (measurable)
- [ ] Duplication removed
- [ ] Performance maintained or improved
- [ ] Readability improved

### Safety
- [ ] No subtle behavior changes
- [ ] Error handling preserved
- [ ] Edge cases still handled
- [ ] Logging maintained

Bug Fix Validation

## Bug Fix Checklist

### Fix Verification
- [ ] Bug no longer reproduces
- [ ] Root cause addressed (not symptom)
- [ ] Regression test added
- [ ] Related issues checked

### Safety
- [ ] Doesn't introduce new bugs
- [ ] Doesn't break other functionality
- [ ] All tests pass
- [ ] Code review approved

### Documentation
- [ ] Bug report updated
- [ ] CHANGELOG entry added
- [ ] Code comments explain fix (if not obvious)

Team Adoption Strategies

Successful AI adoption requires careful planning and change management.

Adoption Phases

Phase 1: Pilot (Weeks 1-4)

Objectives:

Validate value with small group
Identify workflows and best practices
Build internal expertise
Establish baselines

Approach:

Week 1-2: Setup and Training
- Select 2-3 enthusiastic early adopters
- Provide AI tool access
- Conduct training session
- Share this guide

Week 3-4: Guided Usage
- Early adopters use AI for real work
- Daily standup: share experiences
- Document successes and challenges
- Collect metrics (time saved, cost, quality)

Deliverables:
- Usage metrics
- Best practices document
- ROI analysis
- Recommendation for broader rollout

Success Criteria:

20%+ time savings on AI-suitable tasks
No reduction in code quality
Positive feedback from pilot users
Clear ROI (>5:1)

Phase 2: Team Rollout (Weeks 5-12)

Objectives:

Expand to full team
Establish standards and guidelines
Build team capability
Monitor and optimize

Approach:

Week 5-6: Preparation
- Create team guidelines
- Setup cost monitoring
- Prepare training materials
- Establish support channel

Week 7-8: Training and Onboarding
- Team training session (2 hours)
- Hands-on workshop (2 hours)
- Assign mentors (early adopters)
- Provide quick reference guide

Week 9-12: Active Usage
- Daily AI standups (first 2 weeks)
- Weekly metrics review
- Bi-weekly retrospective
- Continuous refinement of practices

Deliverables:
- Team-wide adoption (>80%)
- Documented patterns and anti-patterns
- Cost and productivity metrics
- Refined guidelines

Success Criteria:

80% of team actively using AI
Consistent quality maintained
Positive team sentiment
Measurable productivity gains

Phase 3: Optimization (Week 13+)

Objectives:

Optimize costs and workflows
Advanced technique adoption
Share learnings across organization
Continuous improvement

Approach:

Ongoing Activities:
- Monthly metrics review
- Quarterly workflow optimization
- Share success stories
- Update guidelines based on learnings
- Advanced training sessions

Advanced Techniques:
- Custom prompt libraries
- Automated context assembly
- Integration with dev tools
- Team-specific optimizations

Training Program

Initial Training (2 hours)

Module 1: Introduction (30 min)

Why AI for development
Overview of capabilities
When to use (and not use) AI
Cost structure and budgets

Module 2: Hands-On Basics (45 min)

Tool setup and access
First AI-assisted task
Code generation exercise
Code review exercise
Q&A

Module 3: Workflows and Best Practices (30 min)

Common workflows
Context management
Quality assurance
Cost optimization
Team standards

Module 4: Practice Session (15 min)

Real task from backlog
Guided AI assistance
Review and discuss

Ongoing Learning

Weekly Tips (Slack/Email):

Week 1: Use batching for documentation tasks
Week 2: Try the explore-plan-code workflow
Week 3: Use cheaper models for simple tasks
Week 4: Cache responses for repeated tasks

Monthly Workshops (1 hour):

Month 1: Advanced prompting techniques
Month 2: Complex refactoring with AI
Month 3: Security review patterns
Month 4: Architecture and design with AI

Quarterly Reviews:

Share metrics and ROI
Showcase best examples
Update guidelines
Plan improvements

Standards and Guidelines

Teams MUST establish clear standards:

When AI Use is Required

AI assistance SHOULD be used for:

All documentation generation
Initial code review (before human)
Test case generation
Boilerplate code

When AI Use is Prohibited

AI assistance MUST NOT be used for:

Direct production deployment (without review)
Security-sensitive logic (without expert review)
Regulatory/compliance code (without legal review)
Customer data processing (without privacy review)

Quality Standards

All AI-generated code MUST:

Pass automated checks (lint, test, security)
Undergo human code review
Include tests
Meet team coding standards

AI-generated code SHOULD:

Be reviewed by senior developer (for complex tasks)
Include performance testing (for critical paths)
Be documented with comments explaining complex logic

Measuring Success

Quantitative Metrics

Teams SHOULD track:

Productivity Metrics:

Time saved per task type
Story points per sprint (before/after)
Features delivered per quarter
Time to production (design to deploy)

Quality Metrics:

Bug rate (AI-generated vs manual)
Test coverage
Code review feedback volume
Production incidents

Cost Metrics:

AI cost per developer per month
AI cost per feature delivered
ROI (time saved × developer cost / AI cost)
Cost trend over time

Adoption Metrics:

% developers actively using AI
Requests per developer per week
Variety of use cases
Power user vs casual user ratio

Qualitative Metrics

Teams SHOULD collect:

Developer Satisfaction:

Monthly Survey (1-5 scale):
1. AI tools improve my productivity
2. AI-generated code quality is acceptable
3. I feel confident reviewing AI code
4. Cost/benefit ratio is positive
5. I would recommend AI tools to others

Open questions:
- Best AI experience this month?
- Biggest challenge with AI?
- Feature request or improvement idea?

Code Review Feedback:

Track comments on AI-generated code
Compare to manually written code
Identify common issues
Adjust training and guidelines

Change Management

Addressing Resistance

Common concerns and responses:

“AI will replace developers” Response: AI is a tool that augments, not replaces. It handles repetitive tasks, freeing developers for creative problem-solving, architecture, and complex challenges.

“AI-generated code is low quality” Response: With proper use and review, AI code quality is high. We maintain same standards for all code. Pilot showed equivalent or better quality.

“It’s too expensive” Response: ROI analysis shows 10-50:1 return. A $100/month AI cost saves 10-20 hours of developer time worth $1500-3000.

“I don’t trust AI” Response: Trust through verification. All AI code goes through same review process. You’re the expert ensuring correctness.

“It’s faster to code myself” Response: For some tasks, yes. Use AI where it shines (boilerplate, docs, exploration) and skip it where you’re faster.

Building Champions

Identify and empower champions:

Early adopters from pilot
Respected team members
Different seniority levels
Different specializations

Champion responsibilities:

Mentor others
Share successes
Solve problems
Provide feedback
Represent team in AI discussions

Support champions with:

Advanced training
Direct line to leadership
Recognition and rewards
Time allocated for mentoring
Input on tool selection

Scaling Across Organization

Multi-Team Rollout

Stagger rollout:

Month 1-2: Team A (pilot team)
Month 3-4: Team B and C
Month 5-6: Team D, E, F
Month 7+: Remaining teams

Centralize learning:

Shared documentation repository
Cross-team workshops
Community of practice
Shared metrics dashboard

Customize by team:

Team-specific guidelines
Different tool selections (if needed)
Team-specific prompt libraries
Adapted workflows

Governance

Establish governance structure:

AI Working Group:

Representatives from each team
Meets monthly
Shares learnings
Proposes standards
Evaluates tools

Responsibilities:

Maintain AI usage guidelines
Manage tool licenses and costs
Evaluate new AI capabilities
Ensure security and compliance
Track organization-wide metrics

Decision-making:

Tool selection
Budget allocation
Standard updates
Training requirements
Compliance policies

Long-Term Success Factors

Continuous Improvement

Teams MUST:

Review metrics monthly
Update guidelines quarterly
Retrain on new capabilities
Optimize workflows continuously
Share learnings widely

Staying Current

AI landscape evolves rapidly. Teams SHOULD:

Monitor new model releases
Evaluate new capabilities quarterly
Test new tools in pilot
Update training materials
Adjust cost models

Organizations SHOULD establish:

Internal wiki with AI patterns
Success story repository
Prompt library (team-specific)
Regular knowledge sharing sessions
External community participation

Conclusion

AI-assisted development is a powerful multiplier when used appropriately. Success requires:

Strategic model selection based on task characteristics and cost
Structured workflows that leverage AI strengths
Rigorous quality assurance to maintain code standards
Cost optimization to ensure sustainable adoption
Thoughtful team adoption with proper training and support

Teams that follow these guidelines can expect:

20-40% productivity improvement on suitable tasks
Maintained or improved code quality
Positive ROI (typically 10-50:1)
High developer satisfaction
Competitive advantage in delivery speed

Remember: AI is a tool that augments human intelligence, not a replacement. The developer remains responsible for all code, whether AI-assisted or not.

Appendix: Quick Reference

Model Selection Cheat Sheet

Simple, non-critical → Haiku/GPT-4o mini
Standard development → Sonnet/GPT-4o
Complex reasoning → Opus/GPT-4
High volume, privacy → Self-hosted

Cost Cheat Sheet

Haiku 4.5: ~$0.005 per request
Sonnet: ~$0.01 per request
Opus: ~$0.05 per request
(Based on average 5K token request)

Prompt Templates

Code Generation:

Generate [language] code for [task].

Requirements:
- [requirement 1]
- [requirement 2]

Context:
[relevant code or architecture]

Please include:
- Implementation
- Error handling
- Tests
- Documentation

Code Review:

Review this code:

[code]

Check for:
- Bugs
- Security issues
- Performance problems
- Style violations
- Edge cases

Provide specific feedback with line numbers.

Bug Fix:

Fix this bug:

Error: [error message]
Stack: [stack trace]
Code: [relevant code]

Please:
1. Explain root cause
2. Suggest fix
3. Provide regression test

Documentation Agent Suite

crefft includes a comprehensive multi-agent documentation system - the most advanced open-source AI documentation suite available.

Agent Architecture

┌─────────────────────────────────────────────────────────────────┐
│                   Documentation Agent Suite                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐      │
│  │ doc-architect│ →  │  doc-writer  │ →  │ doc-reviewer │      │
│  │  (planning)  │    │ (generation) │    │ (validation) │      │
│  └──────────────┘    └──────────────┘    └──────────────┘      │
│         │                   │                   │               │
│         ▼                   ▼                   ▼               │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐      │
│  │   doc-sync   │ ←  │doc-publisher │ ←  │  Feedback    │      │
│  │  (freshness) │    │  (formats)   │    │    Loop      │      │
│  └──────────────┘    └──────────────┘    └──────────────┘      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Agents

Agent	Purpose	Invocation
doc-architect	Analyze codebase, create documentation plan	`/doc-plan`
doc-writer	Generate documentation with diagrams	`/doc`
doc-reviewer	Review docs for accuracy and completeness	`/doc-review`
doc-sync	Detect stale documentation	`/doc-sync`
doc-publisher	Transform to llms.txt, MCP, Mermaid	`/doc-publish`

Commands

Command	Description
`/doc [target]`	Generate documentation for file, function, or class
`/doc-plan [dir]`	Create prioritized documentation plan
`/doc-review [file]`	Review documentation for accuracy
`/doc-sync`	Check if docs are synchronized with code
`/doc-sync --pr`	Check docs for files in current PR
`/doc-publish --all`	Generate llms.txt, MCP, and diagrams
`/doc-status`	Show documentation coverage metrics

Output Formats

The doc-publisher agent generates documentation in multiple formats:

Markdown - Standard GitHub-flavored for human developers
llms.txt - Token-efficient format for AI assistants
MCP - Model Context Protocol for AI tool integration
Mermaid - Architecture, sequence, state, and ER diagrams

CI Integration

Documentation workflows integrate with GitHub Actions:

# .github/workflows/doc-sync.yml
# Automatically checks documentation freshness on every PR

Configuration

Agents live in agents/ and slash commands in commands/ at the repository root; configs/claude/ holds Claude Code settings and skills:

crefft/
├── agents/
│   └── docs/
│       ├── architect.md       # Documentation planning
│       ├── writer.md          # Documentation generation
│       ├── reviewer.md        # Documentation review
│       ├── sync.md            # Staleness detection
│       └── publisher.md       # Multi-format output
├── commands/
│   ├── doc.md                 # /doc command
│   ├── doc-plan.md            # /doc-plan command
│   ├── doc-review.md          # /doc-review command
│   ├── doc-sync.md            # /doc-sync command
│   ├── doc-publish.md         # /doc-publish command
│   └── doc-status.md          # /doc-status command
└── configs/
    └── claude/
        └── settings.json      # Claude Code configuration

See Syncing from crefft for installing these into a project’s .claude/ directory.

References

Last Updated: 2025-12-07 Version: 1.0.0 Maintainer: Engineering Team

AI-Assisted Development Overview

RFC 2119 Key Words

Guides in This Section

Table of Contents

Introduction

Scope

Audience

When to Use AI Assistance

Task Types Suitable for AI Assistance

High-Value AI Tasks

Medium-Value AI Tasks

Low-Value AI Tasks

Complexity Level Guidelines

Simple Tasks (< 100 LOC, < 30 minutes)

Moderate Tasks (100-500 LOC, 30 minutes - 4 hours)

Complex Tasks (500+ LOC, > 4 hours)

Decision Tree: Should I Use AI for This Task?

Model Selection Guide

Capability vs Cost Matrix

Model Characteristics Reference

Selection Criteria

When to Use Premium Models (Opus, GPT-4)

When to Use Mid-Tier Models (Sonnet, GPT-4o)

When to Use Budget Models (Haiku, GPT-4o mini)

When to Use Self-Hosted Models

Provider Comparison

Comprehensive Provider Analysis

Provider-Specific Strengths

Anthropic Claude

OpenAI GPT

Google Gemini

Self-Hosted Solutions

Model Recommendations by Task Type

Coding Tasks

Feature Implementation

Bug Fixing

Refactoring

Code Generation (Boilerplate)

Code Review Tasks

Security Review

General Code Review

Performance Review

Documentation Tasks

API Documentation

Code Documentation (Docstrings)

Architecture Documentation

README and Guides

Testing Tasks

Unit Test Generation

Integration Test Generation

Test Data Generation

End-to-End Test Generation

Workflow Patterns

Explore-Plan-Code-Commit Pattern

Phase 1: Explore (Model: Opus/GPT-4 or Sonnet/GPT-4o)

Phase 2: Plan (Model: Opus/GPT-4 or Sonnet/GPT-4o)

Phase 3: Code (Model: Sonnet/GPT-4o or Haiku/mini)

Phase 4: Commit (Model: Haiku/mini for messages)

TDD with AI Pattern

Step 1: Generate Test Cases (Model: Sonnet/GPT-4o)

Step 2: Write Tests First (Model: Sonnet/GPT-4o or Haiku/mini)

Step 3: Implement to Pass Tests (Model: Sonnet/GPT-4o)

Step 4: Refactor (Model: Sonnet/GPT-4o)

Pair Programming with AI Pattern

Continuous Collaboration Mode

Code Review with AI Pattern

Pre-Human Review Pattern

Parallel Review Pattern

Iterative Refinement Pattern

Iteration Cycle

Context Management Strategies

Context Window Optimization

Understanding Context Limits

Prioritizing Context

Context Assembly Strategies

File-Level Context

Module-Level Context

System-Level Context

Context Caching Strategies

Claude Prompt Caching