The AI Development Playbook: The Complete Guide to AI-Assisted Software Engineering

{
  "editor.inlineSuggest.enabled": true,
  "editor.inlineSuggest.showToolbar": "always",
  "github.copilot.enable": {
    "*": true,
    "markdown": true,
    "plaintext": false,
    "yaml": true
  },
  "github.copilot.advanced": {
    "length": 500,
    "temperature": "",
    "top_p": "",
    "stops": {
      "*": ["\n\n\n"]
    }
  },
  "editor.suggest.preview": true,
  "editor.acceptSuggestionOnCommitCharacter": false
}

# AGENTS.md - AI Assistant Configuration

## Project Overview
This is a Next.js 15 e-commerce platform with TypeScript strict mode.
- **Stack**: React 18, Next.js 15, TypeScript 5.3, TailwindCSS, Prisma, PostgreSQL
- **Architecture**: App Router, Server Components, Server Actions
- **Testing**: Vitest, Playwright, React Testing Library

## Critical Rules (NEVER VIOLATE)
1. NEVER use `any` type - use `unknown` and narrow
2. NEVER commit secrets or API keys
3. NEVER disable TypeScript strict checks
4. NEVER skip error handling
5. ALWAYS use parameterized queries (SQL injection prevention)

## Code Style
- Use functional components with hooks
- Prefer named exports over default exports  
- Use early returns to reduce nesting
- Maximum function length: 50 lines
- Maximum file length: 300 lines

## File Organization
\`\`\`
src/
├── app/           # Next.js App Router pages
├── components/    # React components
│   ├── ui/        # Reusable UI primitives
│   └── features/  # Feature-specific components
├── lib/           # Utilities and helpers
├── hooks/         # Custom React hooks
├── types/         # TypeScript type definitions
└── services/      # External API integrations
\`\`\`

## Naming Conventions
- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase with 'use' prefix (useAuth.ts)
- Utilities: camelCase (formatDate.ts)
- Types: PascalCase with descriptive suffix (UserProfileProps)
- Constants: SCREAMING_SNAKE_CASE

## Testing Requirements
- Unit tests for all utility functions
- Integration tests for API routes
- E2E tests for critical user flows
- Minimum 80% coverage for new code

## Common Patterns

### API Route Pattern
\`\`\`typescript
export async function GET(request: Request) {
  try {
    const data = await fetchData();
    return Response.json({ data });
  } catch (error) {
    console.error('[API] Error:', error);
    return Response.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}
\`\`\`

### Component Pattern
\`\`\`typescript
interface Props {
  title: string;
  onAction: () => void;
}

export function MyComponent({ title, onAction }: Props) {
  // Implementation
}
\`\`\`

Here's our existing API route pattern:

\`\`\`typescript
// src/app/api/users/route.ts
export async function GET(request: Request) {
  const session = await getServerSession();
  if (!session) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }
  
  const users = await prisma.user.findMany();
  return Response.json({ data: users });
}
\`\`\`

Create a similar route for /api/products that:
- Requires authentication
- Supports pagination (?page=1&limit=20)
- Filters by category (?category=electronics)
- Returns total count for pagination

Implement a rate limiter with these constraints:
- No external dependencies (use only Node.js built-ins)
- Must be thread-safe for concurrent requests
- Memory efficient (max 10MB for 100K tracked IPs)
- Configurable: requests per window, window size
- Must include TypeScript types
- Include unit tests with Vitest

Review this code for:
1. Security vulnerabilities
2. Performance issues
3. Error handling gaps
4. TypeScript strict mode compliance
5. Edge cases not handled

Then provide an improved version with explanations.

\`\`\`typescript
async function processPayment(userId: string, amount: number) {
  const user = await db.user.findUnique({ where: { id: userId }});
  await stripe.charges.create({
    amount: amount * 100,
    currency: 'usd',
    customer: user.stripeId
  });
  await db.transaction.create({
    data: { userId, amount, status: 'completed' }
  });
}
\`\`\`

Act as a senior security engineer with 15 years of experience 
in application security. Review this authentication flow and 
identify vulnerabilities according to OWASP Top 10 2024.

For each issue found:
- Severity (Critical/High/Medium/Low)
- CWE ID
- Exploitation scenario
- Remediation with code example

Let's build a shopping cart system step by step.

Step 1: Define the TypeScript interfaces for:
- CartItem
- Cart
- CartAction (add, remove, update quantity, clear)

Don't implement yet, just the types.

Step 2: Now implement the cart reducer function using those types.
Use immutable updates and handle all CartAction types.

Bad: "Make this code better"
Good: "Refactor this function to reduce cyclomatic complexity, 
      add error handling for network failures, and improve 
      TypeScript types to eliminate any usage"

Bad: *pastes 500 lines of code* "Fix the bug"
Good: "In the checkout flow (src/lib/checkout.ts:45-67), 
      the calculateTotal function returns NaN when the 
      cart contains items with undefined prices. Fix this 
      to default to 0 for missing prices."

Bad: "Use the standard approach"
Good: "Use React Query v5 with the following configuration..."

Bad: Copy-paste without review
Good: "Let me verify this handles the edge case where..."

I need to optimize a database query that's timing out.

First, analyze the query and explain:
1. What the query is trying to accomplish
2. Why it might be slow (examine each JOIN, WHERE clause)
3. What indexes would help

Then, suggest optimizations:
1. Query restructuring
2. Index recommendations  
3. Caching strategies

Finally, provide the optimized query with comments explaining each change.

Current query:
\`\`\`sql
SELECT u.*, COUNT(o.id) as order_count, SUM(o.total) as lifetime_value
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
WHERE u.created_at > '2024-01-01'
  AND o.status = 'completed'
GROUP BY u.id
ORDER BY lifetime_value DESC
LIMIT 100;
\`\`\`

Generate [component/function/module] with production quality:

Functional Requirements:
- [Specific functionality]

Non-Functional Requirements:
- [ ] TypeScript strict mode compliant
- [ ] Comprehensive error handling
- [ ] Input validation
- [ ] Proper logging
- [ ] Performance optimized
- [ ] Accessible (if UI)
- [ ] Responsive (if UI)

Include:
- [ ] JSDoc documentation
- [ ] Unit tests (Vitest)
- [ ] Usage examples

Create a complete user authentication feature with:

Files needed:
1. src/app/api/auth/[...nextauth]/route.ts - NextAuth config
2. src/lib/auth.ts - Auth utilities
3. src/hooks/useAuth.ts - Client-side auth hook
4. src/components/AuthProvider.tsx - Context provider
5. src/components/LoginForm.tsx - Login UI
6. src/middleware.ts - Route protection

For each file:
- Follow our existing patterns (see AGENTS.md)
- Include proper TypeScript types
- Add error handling
- Include relevant tests

Start with the auth utilities (src/lib/auth.ts), then I'll 
ask for each subsequent file.

I want to implement a password validation function.

First, generate comprehensive test cases covering:
- Minimum length (8 characters)
- Maximum length (128 characters)  
- Requires uppercase
- Requires lowercase
- Requires number
- Requires special character
- No common passwords
- Edge cases (empty, whitespace, unicode)

Then implement the function to pass all tests.

// 1. Always specify the exact signature you want
interface GeneratedFunction {
  name: string;
  params: { name: string; type: string; description: string }[];
  returnType: string;
  throws: string[];
}

// 2. Provide type context upfront
/*
Given these types:
- User { id: string; email: string; role: 'admin' | 'user' }
- Permission { resource: string; action: 'read' | 'write' | 'delete' }

Generate a function that checks if a user has permission...
*/

// 3. Request incremental delivery
/*
Step 1: Generate the function signature and types
Step 2: Implement the core logic
Step 3: Add error handling
Step 4: Add logging
Step 5: Generate tests
*/

Review this pull request for merge readiness.

## Review Criteria

### 1. Correctness
- Does the code do what it claims?
- Are there logical errors?
- Are edge cases handled?

### 2. Security
- SQL injection vulnerabilities?
- XSS vulnerabilities?
- Authentication/authorization issues?
- Sensitive data exposure?

### 3. Performance
- N+1 queries?
- Memory leaks?
- Unnecessary re-renders?
- Missing indexes?

### 4. Maintainability
- Clear naming?
- Appropriate abstractions?
- Code duplication?
- Test coverage?

### 5. Standards Compliance
- TypeScript strict mode?
- Project conventions?
- API consistency?

## Output Format
For each issue:
- File and line number
- Severity (Critical/High/Medium/Low)
- Category
- Problem description
- Suggested fix with code

Code to review:
[paste diff or files]

Generate comprehensive tests for this function:

\`\`\`typescript
export async function transferFunds(
  fromAccount: string,
  toAccount: string, 
  amount: number,
  currency: Currency
): Promise<TransferResult> {
  // Implementation
}
\`\`\`

Test categories to cover:
1. **Happy path**: Successful transfers
2. **Validation**: Invalid inputs (negative amounts, same account, invalid currency)
3. **Edge cases**: Zero amount, maximum amount, floating point precision
4. **Error conditions**: Insufficient funds, account not found, network timeout
5. **Concurrency**: Simultaneous transfers from same account
6. **Security**: SQL injection in account IDs, unauthorized access

Use Vitest with descriptive test names.
Include setup/teardown for database state.
Mock external services appropriately.

Perform a security audit on this authentication module.

Reference frameworks:
- OWASP Top 10 2024
- CWE/SANS Top 25
- NIST guidelines

Check for:
1. **Injection flaws** (SQL, NoSQL, Command, LDAP)
2. **Broken authentication** (weak passwords, session management)
3. **Sensitive data exposure** (encryption, PII handling)
4. **XXE** (XML parsing vulnerabilities)
5. **Broken access control** (IDOR, privilege escalation)
6. **Security misconfiguration** (debug modes, default credentials)
7. **XSS** (reflected, stored, DOM-based)
8. **Insecure deserialization**
9. **Vulnerable dependencies** (known CVEs)
10. **Insufficient logging** (security events)

For each finding, provide:
- CWE ID
- CVSS score estimate
- Proof of concept
- Remediation code

Generate OpenAPI 3.0 documentation for this REST API route:

\`\`\`typescript
// POST /api/orders
export async function POST(request: Request) {
  const session = await getServerSession();
  if (!session) return unauthorized();
  
  const body = await request.json();
  const validated = orderSchema.parse(body);
  
  const order = await prisma.order.create({
    data: {
      userId: session.user.id,
      items: validated.items,
      shippingAddress: validated.shippingAddress,
      total: calculateTotal(validated.items),
    },
    include: { items: true },
  });
  
  await sendOrderConfirmation(session.user.email, order);
  
  return Response.json({ data: order }, { status: 201 });
}
\`\`\`

Include:
- Summary and description
- Request body schema with examples
- Response schemas (success, errors)
- Authentication requirements
- Rate limiting info
- Error codes and meanings

Generate a comprehensive README.md for this project.

Project context:
- [Brief description]
- Tech stack: [list]
- Target audience: [developers/users]

Include sections:
1. **Overview** - What and why
2. **Features** - Key capabilities
3. **Quick Start** - Minimal steps to run
4. **Installation** - Detailed setup
5. **Configuration** - Environment variables
6. **Usage** - Common use cases with examples
7. **API Reference** - Key endpoints/functions
8. **Architecture** - System design overview
9. **Contributing** - How to contribute
10. **License** - License info

Use badges for: build status, coverage, npm version, license.
Include a table of contents.

Help me write an ADR for choosing our state management approach.

Context:
- React 18 application
- Complex forms with validation
- Real-time updates via WebSocket
- Offline capability needed
- Team of 5 developers, mixed experience

Options considered:
1. Redux Toolkit
2. Zustand
3. Jotai
4. React Query + Context

ADR format:
- Title
- Status (Proposed/Accepted/Deprecated)
- Context (problem we're solving)
- Decision (what we chose)
- Consequences (tradeoffs)
- Alternatives Considered

# Team AI Usage Guidelines

## Approved Tools
- GitHub Copilot (all developers)
- Claude Pro (senior developers)
- ChatGPT Plus (architecture discussions)

## Usage Policies

### DO
✅ Use AI for boilerplate and repetitive code
✅ Use AI to explain unfamiliar code
✅ Use AI to generate test cases
✅ Use AI for documentation drafts
✅ Use AI to explore implementation options
✅ Review ALL AI-generated code before committing

### DON'T
❌ Paste proprietary business logic into public AI tools
❌ Commit AI code without understanding it
❌ Use AI for security-critical code without expert review
❌ Share API keys or credentials in prompts
❌ Rely on AI for architectural decisions without team review

## Code Review Checklist for AI-Generated Code
- [ ] I understand every line
- [ ] I've tested edge cases
- [ ] Security implications reviewed
- [ ] Performance implications reviewed
- [ ] Follows team conventions
- [ ] Properly attributed if required

## Sensitive Information
NEVER include in prompts:
- Customer PII
- API keys or secrets
- Proprietary algorithms
- Internal security measures
- Unreleased product details

Document this solution for our team knowledge base:

Problem: [Description of the issue]
Context: [When/where this occurs]
Solution: [The fix we implemented]

Include:
- Root cause analysis
- Step-by-step solution
- Code examples
- Prevention measures
- Related issues/documentation
- Keywords for searchability

// Example: Tracking AI assistance metrics
interface AIMetrics {
  sessionId: string;
  timestamp: Date;
  
  // Usage metrics
  promptCount: number;
  tokensUsed: number;
  
  // Quality metrics
  suggestionsAccepted: number;
  suggestionsRejected: number;
  suggestionsModified: number;
  
  // Outcome metrics
  taskCompletionTime: number;
  bugsIntroduced: number;
  codeReviewCycles: number;
}

// Calculate ROI
function calculateAIROI(metrics: AIMetrics[]): ROIReport {
  const timeSaved = calculateTimeSavings(metrics);
  const qualityImpact = calculateQualityDelta(metrics);
  const cost = calculateAICost(metrics);
  
  return {
    netTimeSavingsHours: timeSaved,
    productivityMultiplier: timeSaved / baselineTime,
    qualityScore: qualityImpact,
    costPerHourSaved: cost / timeSaved,
    recommendation: timeSaved > cost ? 'POSITIVE_ROI' : 'EVALUATE',
  };
}

Before accepting ANY AI-generated code:
1. Can I explain what every line does?
2. What are the edge cases?
3. What could go wrong?
4. Is this the right approach for our codebase?

If you can't answer these → Don't use the code

Always provide fresh, accurate context:
- Current file state (not outdated)
- Relevant type definitions
- Project conventions
- Known constraints

When AI goes off track:
1. Start a new conversation
2. Provide clean context
3. Be more specific about requirements

Design before generating:
1. Write pseudocode or comments first
2. Define interfaces and types
3. List edge cases to handle
4. THEN ask AI to implement

Time ratio guideline:
- 40% thinking/designing
- 20% prompting AI
- 40% reviewing/testing

For any security-sensitive code:
1. Explicitly mention security requirements
2. Ask for threat modeling
3. Request OWASP compliance check
4. Get human security review

Red flags to watch for:
- Direct user input in queries
- Missing authentication checks
- Hardcoded credentials
- Disabled security features

Include quality requirements in prompts:
- "Follow SOLID principles"
- "Use dependency injection for testability"
- "Keep functions under 20 lines"
- "No code duplication"

Schedule regular refactoring:
- Review AI-heavy code weekly
- Run code quality metrics
- Address technical debt in sprints

Skills that become MORE valuable:
✅ System design and architecture
✅ Problem decomposition
✅ Code review and quality assessment
✅ Security and privacy expertise
✅ Domain knowledge
✅ Communication and collaboration

Skills to develop:
✅ Prompt engineering
✅ AI tool evaluation
✅ Human-AI workflow design
✅ AI output validation
✅ Ethical AI usage

Bug: [description]
File: [path:lines]
Expected: [behavior]
Actual: [behavior]
Steps to reproduce: [steps]

Analyze the root cause and provide a minimal fix.

Feature: [name]
Requirements: [list]
Constraints: [list]
Related files: [list]

Implement following our patterns in [example file].

Review for: security, performance, maintainability
Standards: [reference]
Focus areas: [specific concerns]

[code]

Current code: [paste]
Goals:
- Reduce complexity
- Improve testability
- Follow [pattern]

Maintain exact behavior. Include before/after tests.