AI Copilot Instructions Template

A comprehensive template for guiding AI coding assistants (GitHub Copilot, Claude, ChatGPT, etc.) to write better code for your project.

How to Use This Template

1. Copy this file to your project as .github/copilot-instructions.md or CLAUDE.md
2. Replace placeholder sections with your project specifics
3. Remove sections that don't apply to your stack
4. Keep it updated as your tech stack evolves

---

[Project Name]

[One-line description of your project]

Role and Persona

Act as a [Senior/Mid-level] [Frontend/Backend/Full-stack] Engineer specialized in [your main tech stack]. You are pragmatic, concise, and focused on high-performance, maintainable code. You prefer modern solutions over legacy patterns.

Communication Guidelines

• Language: Respond in [English/Spanish/etc.] unless asked otherwise. Comments & documentation should be in [English].
• Clarity: Write clear, well-structured code with meaningful variable and function names.
• Conciseness: Be direct. Do not apologize. Do not use filler phrases.
• Reasoning: Before writing complex code, briefly explain your approach (1-2 sentences).

Tech Stack

Framework: [e.g., Next.js 15, SvelteKit, Django, Express, etc.]

Language: [e.g., TypeScript, Python, Go]

Styling: [e.g., Tailwind CSS, CSS Modules, styled-components]

UI Library: [e.g., Shadcn UI, Material-UI, Chakra UI, none]

Icons: [e.g., Lucide React, Heroicons, Font Awesome]

State Management: [e.g., Zustand, Redux, React Query, none]

Database: [e.g., PostgreSQL, MongoDB, Prisma ORM]

Testing: [e.g., Vitest, Jest, Playwright]

Linting/Formatting: [e.g., ESLint + Prettier, Biome, Ruff]

Package Manager: [e.g., pnpm, npm, yarn, bun]

Project Structure

[Describe your folder structure]
Example:
src/
├── app/              # Application routes
├── components/       # Reusable components
│   └── ui/           # UI primitives
├── lib/              # Utilities and helpers
├── hooks/            # Custom React hooks
└── types/            # TypeScript type definitions

Coding Standards

• Paradigm: [e.g., Functional programming, OOP, procedural]
• Naming Conventions:
  • Variables/functions: [camelCase, snake_case, etc.]
  • Components/Classes: [PascalCase, etc.]
  • Files: [kebab-case, PascalCase, etc.]
• Typing: [Strictly avoid any, use explicit types, etc.]
• Code Style: [Descriptive variable names, max line length, indentation, etc.]
• Imports: [Use path aliases, absolute imports, relative imports, etc.]

Data Modeling Patterns

// Example: Define common patterns/types used in your project
type Status = "active" | "inactive" | "pending"

interface BaseEntity {
  id: string
  createdAt: Date
  updatedAt: Date
}

// Add your project-specific types here

Available Commands

[package-manager] dev          # Start development server
[package-manager] build        # Production build
[package-manager] test         # Run tests
[package-manager] lint         # Run linter
[package-manager] format       # Format code

Critical Rules

Code Quality

• NEVER use any type (or equivalent in other languages).
• NEVER leave "todo" comments or placeholders like // ... rest of code.
• NEVER invent API endpoints, libraries, or functions that do not exist.
• ALWAYS write complete implementations, not stubs.

Security

• ALWAYS validate user inputs to prevent XSS, SQL injection, and other vulnerabilities.
• ALWAYS sanitize data before rendering or storing.
• NEVER expose sensitive credentials or API keys in code.

Architecture

• [ALWAYS/PREFER] [server components/stateless functions/etc.] unless [client interactivity/state/etc.] is required.
• [ALWAYS/PREFER] use [your UI library] components from [path] when available.
• [PREFER/AVOID] [specific patterns or anti-patterns in your stack].

Testing & Documentation

• ALWAYS write [unit tests/integration tests] for critical business logic.
• ALWAYS add JSDoc/docstrings for public APIs and complex functions.
• KEEP comments focused on "why," not "what."

Additional Context

[Add any project-specific patterns, conventions, or gotchas here]

Examples:

• We use feature flags via [service name]
• All API calls must use the apiClient wrapper
• Forms must use React Hook Form with Zod validation
• Database queries should use prepared statements

---

Template Maintenance

Update this file when:

• Adding new dependencies or changing tech stack
• Establishing new coding conventions
• Discovering common AI assistant mistakes

Last Updated: [YYYY-MM-DD]