Custom AI Extensions & Agents

# CLAUDE.md (commit this to your repo)

## Project Overview
This is a multi-tenant SaaS platform for invoice management.
Backend: Node.js + Express + PostgreSQL
Frontend: Next.js 14 App Router + Tailwind

## Code Conventions
- Use named exports only (no default exports)
- All DB queries go through src/db/queries/ — never inline SQL
- Error handling: throw AppError instances, never raw Error
- Logging: import logger from '@/lib/logger', never console.log

## Key Files
- src/db/schema.ts — database types
- src/lib/auth.ts — authentication utilities
- docs/api.md — API documentation

## Testing
- Use vitest + testing-library
- Test files: *.test.ts alongside source files
- Run: npm test (watch), npm run test:ci (CI)

# Add an MCP server to Claude Code:
# ~/.claude/claude_desktop_config.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://localhost/mydb"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your-token" }
    }
  }
}

# Now Claude Code can:
# - Query your database directly
# - Read GitHub issues and PRs
# - Create issues from code TODOs

# Install the MCP SDK:
npm install @modelcontextprotocol/sdk

# src/mcp-server.ts — minimal example
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server(
  { name: 'internal-tools', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

// Register a tool Claude Code can call:
server.setRequestHandler('tools/call', async (request) => {
  if (request.params.name === 'get_feature_flag') {
    const flag = await fetchFromFlagService(request.params.arguments.flag_name);
    return { content: [{ type: 'text', text: JSON.stringify(flag) }] };
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);

// Now claude can: "Check if the new-checkout feature flag is enabled in production"

# Copilot Extensions are GitHub Apps with special capabilities
# They respond to @mentions in Copilot Chat

# Use cases:
# @docs — search internal documentation
# @deploy — check deployment status, trigger deploys
# @oncall — who's on call, open incidents
# @runbook — fetch runbook for a service

# To build one:
# 1. Create a GitHub App at github.com/settings/apps
# 2. Enable Copilot Extension capability
# 3. Implement the extension API endpoint
# 4. Handle the request format from GitHub
# 5. Return streaming responses in the Copilot format

# The extension receives: the user's message + conversation context
# It returns: streamed text back to Copilot Chat

# Team AI Playbook — what to standardize:

# 1. CLAUDE.md in every repo (project context)
# 2. Shared .claude/commands/ committed to repos
#    - /pr-review  — pre-PR checklist
#    - /onboard    — explain the codebase to new devs
#    - /debug      — structured debugging workflow

# 3. Agreed prompt patterns for common tasks:
#    - Commit messages: conventional commits format
#    - PR descriptions: summary + test plan + breaking changes
#    - Code review: always ask for severity classification

# 4. MCP servers for shared tooling:
#    - Internal docs
#    - Feature flags
#    - Deployment pipelines

# 5. AI usage guidelines:
#    - Always review AI-generated code before committing
#    - No AI-generated code in security-critical paths without senior review
#    - AI for acceleration, not substitution of understanding