AGENTS.md: How to Configure Claude Code for Your Project (2026)

# AGENTS.md - Project Configuration

## Project Overview
project_name: "TaskFlow - Project Management Platform"
project_type: "full-stack-web-application"
repository: "https://github.com/company/taskflow"
primary_language: "TypeScript"
framework: "React 18 + Next.js 14"

## Technical Stack
frontend:
  framework: "React 18 with TypeScript"
  build_tool: "Next.js 14"
  styling: "Tailwind CSS + Headless UI"
  state_management: "Zustand + React Query"
  testing: "Vitest + React Testing Library"

backend:
  runtime: "Node.js 18+"
  framework: "Express.js"
  database: "PostgreSQL with Prisma ORM"
  authentication: "NextAuth.js"
  api_style: "REST with OpenAPI documentation"

deployment:
  frontend: "Vercel"
  backend: "Railway"
  database: "Supabase"
  monitoring: "Sentry + Vercel Analytics"

## Development Standards
code_style:
  typescript: "strict mode enabled"
  formatting: "Prettier with 2-space indents"
  linting: "ESLint with Airbnb configuration"
  naming: "camelCase variables, PascalCase components"
  imports: "absolute imports from src/, group by type"

## Project Goals
primary_objectives:
  - "Deliver MVP by Q2 2026"
  - "Support 10,000+ concurrent users"
  - "Maintain 99.9% uptime SLA"
  - "Achieve accessibility compliance (WCAG 2.1 AA)"

## Project Identity
name: "E-commerce Analytics Dashboard"
domain: "B2B SaaS for e-commerce optimization"
target_users: "E-commerce managers and marketing teams"
key_features:
  - "Real-time sales analytics"
  - "Customer behavior tracking"
  - "Inventory management"
  - "Marketing campaign analysis"

business_context:
  stage: "Series A startup"
  team_size: "12 developers"
  users: "500+ paying customers"
  growth_rate: "25% month-over-month"
  market_focus: "Small to medium e-commerce businesses"

## Architecture Guidelines
system_architecture:
  pattern: "feature-based modular architecture"
  data_flow: "unidirectional with React Query for server state"
  component_hierarchy: "pages → features → components → ui"

folder_structure: |
  src/
    app/                 # Next.js 14 app router
      (dashboard)/       # Route groups
      api/              # API routes
    components/
      ui/               # Reusable UI components
      forms/            # Form components
      layout/           # Layout components
    features/
      analytics/        # Analytics feature module
      inventory/        # Inventory feature module
    lib/
      api/              # API client and types
      utils/            # Utility functions
      hooks/            # Custom React hooks
    types/              # TypeScript type definitions

design_patterns:
  components: "composition over inheritance"
  state: "local state for UI, server state for data"
  error_handling: "error boundaries + React Query error states"
  loading: "skeleton screens + optimistic updates"

## Code Quality Standards
typescript_requirements:
  strict_mode: true
  no_any_type: "use proper typing with interfaces"
  return_types: "required for all functions"
  prop_types: "use interfaces for React component props"

react_patterns:
  component_style: "functional components with hooks only"
  prop_drilling: "avoid - use context or state management"
  side_effects: "use useEffect with proper cleanup"
  performance: "React.memo for expensive components"
  accessibility: "proper ARIA labels and semantic HTML"

testing_requirements:
  coverage_minimum: "80%"
  test_types: "unit tests for utilities, integration tests for features"
  test_structure: "describe blocks for feature grouping"
  mocking: "mock external dependencies and API calls"
  accessibility_testing: "include jest-axe in component tests"

security_standards:
  input_validation: "validate all user inputs with Zod"
  api_security: "authenticate all API routes"
  data_sanitization: "sanitize before database operations"
  error_handling: "never expose internal errors to users"

## Development Workflow
git_workflow:
  branching: "feature branches from main"
  naming: "feature/description or fix/description"
  commits: "conventional commits (feat:, fix:, docs:, etc.)"
  review_process: "all changes require code review"

ci_cd_pipeline:
  testing: "all tests must pass before merge"
  linting: "ESLint and Prettier checks required"
  type_checking: "TypeScript compilation must succeed"
  build: "Next.js build must complete successfully"
  deployment: "automatic to staging, manual to production"

code_review_criteria:
  functionality: "does the code solve the intended problem?"
  performance: "are there any performance implications?"
  security: "are there any security vulnerabilities?"
  maintainability: "is the code easy to understand and modify?"
  testing: "are appropriate tests included?"

documentation_requirements:
  code_comments: "explain complex business logic"
  api_documentation: "OpenAPI specs for all endpoints"
  component_documentation: "Storybook stories for UI components"
  readme_updates: "update README for new setup steps"

## Development Environment
required_tools:
  runtime: "Node.js 18.17.0 or higher"
  package_manager: "pnpm (preferred) or npm"
  ide_recommendations: "VS Code with recommended extensions"
  database: "PostgreSQL 15+ (local or Docker)"

vs_code_extensions:
  - "ESLint"
  - "Prettier"
  - "TypeScript Hero"
  - "Tailwind CSS IntelliSense"
  - "GitLens"
  - "Error Lens"

environment_variables:
  development: ".env.local"
  staging: ".env.staging"
  production: "managed through deployment platform"
  
database_setup:
  local: "Docker Compose with PostgreSQL"
  migrations: "Prisma migrate for schema changes"
  seeding: "npm run db:seed for development data"

# AGENTS.md - React TypeScript Application

## Project Configuration
name: "Customer Support Dashboard"
type: "react-typescript-spa"
framework: "React 18 + TypeScript 5 + Vite"

## React-Specific Guidelines
component_patterns:
  style: "functional components with TypeScript"
  props: "use interfaces, never inline prop types"
  state: "useState for simple state, useReducer for complex"
  effects: "useEffect with cleanup functions"
  refs: "useRef for DOM manipulation, forwardRef for component refs"

typescript_integration:
  strict_mode: true
  interfaces: "define all props, state, and API response types"
  generics: "use for reusable components and hooks"
  utility_types: "leverage Pick, Omit, Partial appropriately"
  event_types: "use React.MouseEvent, React.FormEvent, etc."

performance_optimization:
  memoization: "React.memo for expensive components"
  callbacks: "useCallback for functions passed as props"
  computations: "useMemo for expensive calculations"
  lazy_loading: "React.lazy for code splitting"
  bundle_analysis: "regular bundle size monitoring"

state_management_strategy:
  local_state: "useState/useReducer within components"
  shared_state: "Zustand stores for app-wide state"
  server_state: "React Query for API data management"
  form_state: "React Hook Form for complex forms"

testing_approach:
  unit_tests: "test utilities and custom hooks"
  component_tests: "render testing with React Testing Library"
  integration_tests: "test feature workflows"
  accessibility_tests: "jest-axe for accessibility compliance"

# AGENTS.md - Next.js Full-Stack Application

## Project Configuration
name: "SaaS Platform"
type: "nextjs-fullstack"
framework: "Next.js 14 + App Router"

## Next.js Specific Patterns
app_router_usage:
  file_conventions: "page.tsx, layout.tsx, loading.tsx, error.tsx"
  route_groups: "use (groups) for organization without URL impact"
  dynamic_routes: "[param] for dynamic segments"
  parallel_routes: "@folder for parallel route segments"

server_components:
  default: "use Server Components by default"
  client_components: "add 'use client' only when needed"
  data_fetching: "fetch data in Server Components when possible"
  streaming: "use Suspense for progressive loading"

api_routes:
  structure: "app/api/[...routes]/route.ts"
  methods: "export named functions (GET, POST, PUT, DELETE)"
  validation: "use Zod for request validation"
  error_handling: "return consistent error response format"

performance_optimization:
  images: "use next/image with proper sizing and optimization"
  fonts: "use next/font for font optimization"
  metadata: "use generateMetadata for dynamic SEO"
  caching: "leverage Next.js caching strategies"

deployment_considerations:
  vercel: "optimal deployment platform"
  environment: "use Vercel environment variables"
  analytics: "Vercel Analytics for performance monitoring"
  edge_functions: "consider edge runtime for global performance"

# AGENTS.md - Node.js Express API

## Project Configuration
name: "RESTful API Service"
type: "nodejs-express-api"
framework: "Express.js + TypeScript"

## API Design Principles
rest_conventions:
  endpoints: "use RESTful URL patterns (/users/:id)"
  methods: "GET for retrieval, POST for creation, PUT for updates"
  status_codes: "use appropriate HTTP status codes"
  pagination: "implement cursor-based pagination"
  versioning: "version APIs with /v1/ prefix"

middleware_stack:
  cors: "configure for frontend domains"
  helmet: "security headers"
  compression: "gzip compression"
  rate_limiting: "API rate limiting"
  logging: "structured logging with winston"
  validation: "request validation with express-validator"

database_integration:
  orm: "Prisma for type-safe database access"
  migrations: "version controlled schema changes"
  transactions: "use for multi-step operations"
  connection_pooling: "configure appropriate pool size"

error_handling:
  global_handler: "centralized error handling middleware"
  error_types: "custom error classes for different scenarios"
  logging: "log errors with appropriate detail levels"
  user_responses: "safe error messages for end users"

security_implementation:
  authentication: "JWT with proper expiration"
  authorization: "role-based access control"
  input_validation: "validate and sanitize all inputs"
  sql_injection: "use parameterized queries"
  rate_limiting: "implement per-route rate limits"

## Environment-Specific Settings
development:
  debug_mode: true
  hot_reload: true
  detailed_logging: true
  mock_external_apis: true
  test_database: "local PostgreSQL instance"

staging:
  debug_mode: false
  performance_monitoring: true
  realistic_data: true
  external_api_integration: true
  ssl_required: true

production:
  debug_mode: false
  error_tracking: "Sentry integration"
  performance_monitoring: "full monitoring suite"
  caching: "Redis for session and data caching"
  cdn: "CloudFront for static assets"
  security: "maximum security headers and validation"

## Environment-Specific Code Guidelines
environment_detection:
  use: "process.env.NODE_ENV"
  avoid: "hardcoded environment checks"
  configuration: "centralize env-specific settings"

## Team Collaboration
code_ownership:
  frontend: "frontend team owns /src/components and /src/pages"
  backend: "backend team owns /src/api and database schemas"
  shared: "both teams collaborate on /src/types and API contracts"

communication_patterns:
  api_changes: "notify frontend team before breaking changes"
  schema_changes: "coordinate database migrations with deployment"
  dependency_updates: "team lead approval for major version bumps"
  security_updates: "immediate review and deployment required"

review_assignments:
  frontend_changes: "require frontend team member review"
  backend_changes: "require backend team member review"
  critical_paths: "require senior developer approval"
  security_related: "require security-focused review"

conflict_resolution:
  technical_disputes: "architect has final decision"
  priority_conflicts: "product manager resolves"
  resource_conflicts: "engineering manager mediates"

## Performance Standards
frontend_performance:
  lighthouse_score: "90+ for all pages"
  core_web_vitals:
    lcp: "< 2.5 seconds"
    fid: "< 100 milliseconds"
    cls: "< 0.1"
  bundle_size: "< 250KB gzipped for initial load"
  image_optimization: "WebP format with fallbacks"

backend_performance:
  response_time: "95th percentile < 500ms"
  database_query: "< 100ms for 95% of queries"
  api_rate_limits: "1000 requests per minute per user"
  memory_usage: "< 512MB per instance"

monitoring_implementation:
  error_tracking: "Sentry for error monitoring"
  performance_tracking: "Core Web Vitals monitoring"
  uptime_monitoring: "external service for uptime checks"
  database_monitoring: "query performance and slow query alerts"

alerting_thresholds:
  error_rate: "alert if > 1% error rate"
  response_time: "alert if 95th percentile > 1000ms"
  memory_usage: "alert if > 80% memory utilization"
  database_connections: "alert if > 80% connection pool usage"

## Maintenance Schedule
weekly_reviews:
  - "Update current sprint context"
  - "Add new coding patterns discovered"
  - "Remove deprecated guidelines"

monthly_updates:
  - "Review and update dependency versions"
  - "Assess performance targets and adjust if needed"
  - "Update team structure and responsibilities"
  - "Sync with project roadmap changes"

quarterly_assessments:
  - "Major architecture review and updates"
  - "Technology stack evaluation and upgrades"
  - "Security guideline review and enhancement"
  - "Process improvement integration"

project_milestone_updates:
  - "Update goals and priorities"
  - "Revise performance targets"
  - "Integrate lessons learned"
  - "Adjust team collaboration patterns"

## Configuration Testing Scenarios
component_generation:
  test: "Ask Claude to create a new React component"
  verify: "Generated code follows TypeScript patterns"
  check: "Component structure matches project conventions"

api_endpoint_creation:
  test: "Request new API endpoint implementation"
  verify: "Follows REST conventions and error handling"
  check: "Includes proper validation and testing"

bug_fixing:
  test: "Present a common bug scenario"
  verify: "Solution follows debugging methodology"
  check: "Includes prevention strategies and tests"

refactoring_guidance:
  test: "Ask for refactoring suggestions on complex code"
  verify: "Maintains functionality while improving structure"
  check: "Considers performance and maintainability"

## VS Code Configuration
settings.json:
  "claude.configFile": "./AGENTS.md"
  "claude.autoLoad": true
  "claude.contextAware": true
  "claude.projectRootDetection": true

recommended_extensions:
  claude_code: "Official Claude Code extension"
  typescript: "TypeScript and JavaScript support"
  eslint: "Code linting integration"
  prettier: "Code formatting"
  gitlens: "Git integration and history"

workspace_settings:
  auto_format_on_save: true
  organize_imports_on_save: true
  claude_suggestions_enabled: true
  inline_claude_help: true

## Continuous Integration
agents_md_validation:
  lint_check: "validate AGENTS.md syntax and structure"
  consistency_check: "ensure configuration matches codebase"
  security_review: "scan for security-related configurations"
  performance_check: "validate performance target feasibility"

automated_updates:
  dependency_sync: "update tech stack versions automatically"
  security_patches: "integrate security guideline updates"
  performance_benchmarks: "update targets based on metrics"
  
quality_gates:
  agents_md_approval: "require approval for configuration changes"
  impact_assessment: "analyze impact of configuration modifications"
  rollback_plan: "automated rollback for problematic configurations"

## Improvement Workflow
feedback_collection:
  developer_surveys: "monthly satisfaction surveys"
  code_review_analysis: "track common issues in AI-generated code"
  performance_metrics: "monitor development velocity impact"
  error_tracking: "categorize and analyze recurring problems"

optimization_cycle:
  weekly: "minor configuration adjustments based on recent feedback"
  monthly: "comprehensive review of effectiveness metrics"
  quarterly: "major configuration overhaul based on project evolution"
  annually: "complete methodology review and best practice updates"

success_measurement:
  productivity_gains: "measure development velocity improvements"
  code_quality: "track defect rates in AI-generated vs manual code"
  team_satisfaction: "regular surveys on AI assistance effectiveness"
  learning_acceleration: "measure how quickly new team members become productive"

## Technology Evolution Planning
current_stack_lifecycle:
  react: "stay current with latest stable version"
  typescript: "upgrade to new versions within 6 months"
  nextjs: "evaluate new features quarterly"
  database: "plan for horizontal scaling requirements"

experimental_technologies:
  evaluation_criteria: "performance, stability, ecosystem support"
  pilot_process: "small feature implementation before full adoption"
  team_training: "dedicated learning time for new technologies"
  migration_strategy: "phased approach with rollback plans"

configuration_versioning:
  semantic_versioning: "major.minor.patch for AGENTS.md changes"
  backward_compatibility: "maintain support for previous patterns"
  deprecation_notices: "clear timeline for retiring old patterns"
  migration_guides: "step-by-step upgrade instructions"