AI-Assisted Development

Location: /CLAUDE.md (repository root)

Purpose: Provides comprehensive guidance to all AI assistants about OneApp monorepo structure, conventions, and best practices.

Key Sections:

• Tool Usage Priority — Mandatory order: Claude Code tools → MCP tools → GitHub CLI → Bash
• Project Overview — Stack: Next.js 16, React 19, TypeScript 5, pnpm monorepo
• Workspace Structure — packages/, teams/, personal/, platform/ organization
• Architecture Patterns — AsyncResult, branded types, 5-layer API architecture
• Code Standards — Naming conventions, import order, TypeScript strictness
• Testing Setup — Vitest 4, @testing-library/react, coverage thresholds
• Git Workflow — Conventional commits, Changesets, Mergify merge queue
• Development Tools — CodeRabbit AI, GitHub Actions, MCP servers

When to Update:

• Adding new shared packages (update package reference)
• Changing architecture patterns (update best practices)
• Modifying workspace structure (update directory reference)
• Updating tech stack versions (update requirements)

Example Content:

## ⚠️ Requirements

Only Next.js 16+ and Vercel AI SDK v6+ are supported.

## Shared Package Reference

- `@repo/types`: Brand<T, Brand>, AsyncResult<T>, ApiResponse<T>
- `@repo/ui`: React components (Button with variants)
- `@repo/utils`: cn(), debounce(), formatDate(), isValidEmail()

Location: /.github/claude-instructions.md

Purpose: Claude Code-specific development patterns, JSDoc standards, and code review guidelines.

Key Sections:

• Role & Behavior — Act as user's developer, proactive code review, self-directed action
• Function Documentation — Comprehensive JSDoc with examples and edge cases
• Inline Comments — Explain "why" rather than "what"
• Type Safety — No any types, explicit return types, branded types usage
• Component Patterns — Server Components by default, "use client" only when needed
• API Routes — AsyncResult pattern, proper error handling, OpenAPI generation
• Testing Requirements — Vitest, @testing-library/react, >80% coverage

Example JSDoc Pattern:

/**
 * Combines class names conditionally using clsx.
 * Filters out falsy values and merges Tailwind classes intelligently.
 *
 * @param inputs - Class names, objects, or arrays of class names
 * @returns Merged class string with conflicts resolved
 *
 * @example
 * cn('btn', 'btn-primary', isDisabled && 'opacity-50')
 * // Output: 'btn btn-primary opacity-50' (if isDisabled is true)
 * // Output: 'btn btn-primary' (if isDisabled is false)
 */
export function cn(...inputs: ClassValue[]): string {
  return twMerge(clsx(inputs));
}

Location: /.github/copilot-instructions.md

Purpose: GitHub Copilot-specific component patterns, import guidelines, and daily development workflows.

Key Sections:

• Component Guidelines — Server vs Client Components, composition patterns
• Import Patterns — Separated type imports, workspace package usage
• API Route Patterns — AsyncResult, Zod validation, proper error responses
• Testing Patterns — Vitest setup, component testing, hook testing
• Agent Integration — How to invoke specialized agents

Example Server Component Pattern:

import type { ReactNode } from "react";

/**
 * Card component for displaying content in a bordered container.
 * This is a Server Component (default in Next.js 16).
 */
export interface CardProps {
  children: ReactNode;
  title?: string;
  className?: string;
}

export function Card({ children, title, className = "" }: CardProps) {
  return (
    <div className={`border rounded-lg p-4 ${className}`}>
      {title && <h3 className="text-lg font-semibold mb-2">{title}</h3>}
      {children}

  );
}

Example Client Component Pattern:

"use client";

import { useState } from "react";
import type { ReactNode } from "react";

/**
 * Accordion component with collapsible content.
 * Uses "use client" because it manages interactive state.
 */
export function Accordion({ children }: { children: ReactNode }) {
  const [isOpen, setIsOpen] = useState(false);
  return <div onClick={() => setIsOpen(!isOpen)}>{isOpen && children};
}

Location: /.github/cursor-instructions.md

Purpose: Cursor-specific rapid prototyping patterns and AI chat workflows.

Key Sections:

• Rapid Prototyping — Fast iteration patterns, experimental features
• AI Chat Workflows — Effective prompting for Cursor's chat interface
• Code Generation — Component scaffolding, boilerplate reduction

File: .github/agents/development-agent.yml (v1.0.0)

Capabilities:

• React Server and Client Component development
• Next.js 16 App Router implementation
• TypeScript type-safe code generation
• API route creation with proper error handling
• Custom hook development
• Shared package integration (@repo/ui, @repo/types, @repo/utils)
• Monorepo-aware development
• Code refactoring and optimization

Usage:

# Via GitHub Copilot Chat
@repo Use the development agent to create a ProductCard component

# Example prompt
"Development agent: Create a Server Component for displaying product information
with image, title, description, and price"

Key Features:

• ✅ Enforces Server Components by default
• ✅ Proper TypeScript with no any types
• ✅ Separated type imports
• ✅ JSDoc comments on all exports
• ✅ Uses shared packages correctly
• ✅ Follows monorepo patterns

Generated Code Example:

import type { Product } from "@repo/types";
import { formatCurrency } from "@repo/utils";
import Image from "next/image";

/**
 * ProductCard displays product information in a card layout.
 * Server Component - fetches product data on the server.
 */
export interface ProductCardProps {
  product: Product;
}

export function ProductCard({ product }: ProductCardProps) {
  return (
    <div className="border rounded-lg p-4">
      <Image src={product.imageUrl} alt={product.name} width={300} height={200} />
      <h3 className="text-lg font-semibold">{product.name}</h3>
      <p className="text-gray-600">{product.description}</p>
      <p className="text-xl font-bold">{formatCurrency(product.price)}</p>

  );
}

File: .github/agents/code-review-agent.yml (v1.0.0)

Capabilities:

• TypeScript type checking validation
• Import pattern validation
• Server/Client Component usage verification
• Next.js App Router best practices enforcement
• Security vulnerability detection
• Code quality assessment
• Performance optimization suggestions
• Monorepo pattern compliance

Usage:

# Via GitHub Copilot Chat
@repo Use the code review agent to review my recent changes

# Automated in CI/CD
# Can be integrated into GitHub Actions workflow

Review Categories:

• 🔴 Critical Issues — Must fix before merge (type errors, security vulnerabilities)
• ⚠️ Warnings — Should address (missing type imports, incorrect patterns)
• 💡 Suggestions — Nice to have (performance optimizations, readability)
• 🔒 Security — Security concerns (XSS risks, missing validation)
• ⚡ Performance — Optimization opportunities (unnecessary re-renders, bundle size)

Example Review Output:

🔴 Critical: Missing type import in UserProfile.tsx:5
- Change: import { User } from "@repo/types"
- To: import type { User } from "@repo/types"

⚠️ Warning: Client Component used unnecessarily in Dashboard.tsx
- This component has no state or event handlers
- Remove "use client" directive to make it a Server Component

💡 Suggestion: Consider using AsyncResult for error handling in api/users/route.ts
- Current: try/catch with Response.json({ error })
- Recommended: AsyncResult<User[]> pattern for type-safe errors

File: .github/agents/test-generator-agent.yml (v1.0.0)

Capabilities:

• Vitest test generation
• React Testing Library integration
• Component testing (Server and Client)
• Hook testing with renderHook
• API route testing
• Utility function testing
• Coverage optimization (>80% target)
• Test fixture creation

Usage:

# Via GitHub Copilot Chat
@repo Test generator agent: Create tests for the SearchBox component

# Example prompt
"Generate comprehensive tests for the UserProfile component including
rendering, user interactions, and edge cases"

Test Patterns Generated:

• ✅ Rendering tests — Component renders correctly with different props
• ✅ User interaction tests — Clicks, inputs, form submissions work
• ✅ Props validation tests — Component handles all prop variations
• ✅ State change tests — State updates trigger correct behavior
• ✅ Edge case tests — Handles empty states, errors, loading states
• ✅ Accessibility tests — ARIA labels, keyboard navigation
• ✅ Error handling tests — Proper error messages and boundaries

Coverage Target: >80% for statements, branches, functions, and lines

Generated Test Example:

import { render, screen } from "@testing-library/react";
import { userEvent } from "@testing-library/user-event";
import { SearchBox } from "./SearchBox";

describe("SearchBox", () => {
  it("renders search input", () => {
    render(<SearchBox onSearch={vi.fn()} />);
    expect(screen.getByPlaceholderText("Search...")).toBeInTheDocument();
  });

  it("calls onSearch when user types and submits", async () => {
    const onSearch = vi.fn();
    render(<SearchBox onSearch={onSearch} />);

    const input = screen.getByPlaceholderText("Search...");
    await userEvent.type(input, "test query");
    await userEvent.keyboard("{Enter}");

    expect(onSearch).toHaveBeenCalledWith("test query");
  });

  it("shows no results message when query is empty", () => {
    render(<SearchBox onSearch={vi.fn()} />);
    expect(screen.getByText("Enter a search query")).toBeInTheDocument();
  });
});

File: .github/agents/security-audit-agent.yml (v1.0.0)

Capabilities:

• Secret detection and prevention (hardcoded API keys, passwords)
• Input validation verification (Zod schemas, sanitization)
• Authentication and authorization checks (session validation, RBAC)
• XSS and injection prevention (SQL injection, command injection)
• Dependency security scanning (vulnerable packages)
• Secure configuration validation (HTTPS, CSP headers)
• OWASP Top 10 compliance checking (all 10 categories)
• PII and sensitive data protection (user data handling)

Usage:

# Via GitHub Copilot Chat
@repo Security audit agent: Review this API route for vulnerabilities

# Example prompt
"Run security audit on the user registration API route"

Security Categories:

• 🔴 Critical — Hardcoded secrets, SQL injection, auth bypass (fix immediately)
• ⚠️ High — XSS, missing validation, authorization issues (fix before merge)
• 📋 Medium — Missing rate limiting, weak encryption (address soon)
• ℹ️ Low — Missing security headers, verbose errors (nice to have)

OWASP Top 10 Coverage:

1. ✅ Broken Access Control
2. ✅ Cryptographic Failures
3. ✅ Injection
4. ✅ Insecure Design
5. ✅ Security Misconfiguration
6. ✅ Vulnerable and Outdated Components
7. ✅ Identification and Authentication Failures
8. ✅ Software and Data Integrity Failures
9. ✅ Security Logging and Monitoring Failures
10. ✅ Server-Side Request OneAppry (SSRF)

Example Audit Output:

🔴 Critical: Hardcoded API key detected in utils/api.ts:12
- Line: const API_KEY = "sk_live_abc123xyz"
- Fix: Use environment variable: process.env.API_KEY

⚠️ High: Missing input validation in api/users/route.ts
- User input from request.json() is not validated
- Add Zod schema validation before database insertion

📋 Medium: No rate limiting on authentication endpoint
- Endpoint: api/auth/login/route.ts
- Add rate limiting with @repo/security rate limiter

File: .github/agents/merge-remediation-agent.yml (v1.0.0)

Capabilities:

• Detect agentic branches (cursor/codex/copilot/claude prefixes)
• Apply unresolved code review comments automatically
• Parse suggestions from CodeRabbit, Cursor, Codex, Claude, and Copilot
• Rebase destination branch into current branch
• LLM-powered conflict analysis and resolution
• Context-aware merging of complementary changes
• Automatic resolution of safe conflicts (formatting, imports)
• Flagging of risky conflicts for manual review (logic changes)
• Comprehensive validation and rollback support

Usage:

# Step 1: Apply review comments first
pnpm comments:analyze  # Dry-run to see what would be applied
pnpm comments:apply    # Apply safe suggestions

# Step 2: Remediate merge conflicts
pnpm merge:analyze     # Analyze conflicts
pnpm merge:remediate   # Auto-resolve safe conflicts

# Via GitHub Copilot
@repo Use the merge remediation agent to resolve conflicts in this PR

Conflict Resolution Strategies:

• ✅ Safe Auto-Resolution — Formatting differences, import order, whitespace
• ✅ Complementary Merging — Both branches add new features without overlap
• ⚠️ Manual Review Required — Logic changes, API modifications, schema updates

Example Workflow:

# Scenario: PR #123 has merge conflicts in api/users/route.ts

# 1. Analyze conflicts
$ pnpm merge:analyze
Conflicts detected in:
  - api/users/route.ts (3 conflicts)
    * Conflict 1: Import order (safe auto-resolve)
    * Conflict 2: New field added in both branches (complementary merge)
    * Conflict 3: Different error handling logic (manual review)

# 2. Auto-resolve safe conflicts
$ pnpm merge:remediate
✅ Resolved: Import order in api/users/route.ts
✅ Merged: New fields (email, phone) from both branches
⚠️ Flagged: Error handling logic requires manual review

# 3. Manual review of flagged conflict
# Review the marked section and choose appropriate logic

Problem: AI suggests imports or APIs that don't exist in OneApp.

Solution:

1. Check if AI is using outdated instruction files
2. Update CLAUDE.md with current package APIs
3. Provide explicit context in prompt: "Use the latest @repo/auth from workspace packages"
4. Reference existing code: "Follow the pattern in app/dashboard/page.tsx"

Example:

# ❌ Vague prompt
"Add authentication to this page"

# ✅ Specific with current APIs
"Add authentication using @repo/auth/server/next auth.api.getSession() like
in platform/apps/oneapp-onstage/app/dashboard/page.tsx"

Problem: AI adds "use client" unnecessarily or forgets it when needed.

Solution:

1. Explicitly state component type in prompt
2. Reference .github/copilot-instructions.md Server/Client examples
3. Use Code Review Agent to catch incorrect usage

Example:

# ✅ Explicit component type
"Create a Server Component that fetches user data (no state, no events)"
"Create a Client Component with a search input (needs useState and onChange)"

Problem: AI generates try/catch with plain Error objects instead of AsyncResult pattern.

Solution:

1. Mention AsyncResult explicitly in prompts
2. Update .github instruction files with more AsyncResult examples
3. Use Code Review Agent to flag non-compliant error handling

Example:

# ✅ Specify error handling pattern
"Create an API route that returns AsyncResult<User[]> following the pattern in
guides/error-handling.mdx"

Problem: AI uses plain string for user IDs, product IDs, etc.

Solution:

1. Reference branded types in CLAUDE.md more prominently
2. Provide examples in prompts
3. Use Code Review Agent to catch plain string usage

Example:

# ✅ Request branded types
"Create a function that accepts UserId (branded type from @repo/types) and
returns AsyncResult<User>"

Creating a New Specialized Agent:

1. Identify the Need:

   • Recurring workflow that requires specific context
   • Examples: "Migration Agent" for database schema changes, "Documentation Agent" for API docs generation

2. Create Agent File:

   # Create new agent YAML file
   touch .github/agents/my-custom-agent.yml

3. Define Agent Structure:

   name: my-custom-agent
   version: 1.0.0
   description: |
     Custom agent for [specific workflow].
   
   capabilities:
     - Capability 1
     - Capability 2
   
   usage:
     prompt: "@repo Use the [agent-name] agent to [task]"
   
   context:
     - path: packages/
       purpose: Access to shared packages
     - path: .github/claude-instructions.md
       purpose: Follow OneApp patterns
   
   instructions: |
     You are a specialized agent for [workflow].
   
     When invoked:
     1. Step 1
     2. Step 2
     3. Step 3
   
     Output format: [description]

4. Test Agent:

   @repo Use the my-custom-agent to [test task]

5. Document in README:

   • Add agent to AGENTS.md
   • Include usage examples
   • Document capabilities and when to use

Automating Agent Usage in GitHub Actions:

# .github/workflows/ai-quality-checks.yml
name: AI Quality Checks

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  code-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Run Code Review Agent
        uses: github/copilot-cli-action@v1
        with:
          agent: code-review-agent
          prompt: "Review all changes in this PR"

      - name: Comment Results
        uses: actions/github-script@v6
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              body: process.env.REVIEW_OUTPUT
            })

  security-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Run Security Audit Agent
        uses: github/copilot-cli-action@v1
        with:
          agent: security-audit-agent
          prompt: "Audit all changes for security vulnerabilities"

      - name: Fail on Critical Issues
        run: |
          if grep -q "🔴 Critical" audit-output.txt; then
            echo "Critical security issues found!"
            exit 1
          fi

Managing Instruction Files as Code:

1. Version Control:

   • All instruction files in .github/ are version controlled
   • Changes trigger AI assistant updates automatically

2. Change Process:

   # 1. Update instruction file
   vim .github/copilot-instructions.md
   
   # 2. Test with AI assistant
   @repo Test new instruction: [prompt]
   
   # 3. Commit with conventional commit
   git commit -m "docs: update Copilot instructions for AsyncResult pattern"
   
   # 4. Create PR for team review
   gh pr create --title "docs: update AI instruction files"

3. Breaking Changes:

   • Document in CHANGELOG.md
   • Notify team in PR description
   • Provide migration guide if patterns change

4. Rollback Strategy:

   # If new instructions cause issues, revert
   git revert <commit-hash>
   git push

Combining Multiple AI Tools for Complex Tasks:

Scenario: Building a new feature end-to-end

# Step 1: Planning with Claude Code
# Prompt: "Plan the architecture for a user notification system with
# WebSocket support, database persistence, and email integration"
# Claude provides: Architecture diagram, package selection, file structure

# Step 2: Component Development with GitHub Copilot + Development Agent
@repo Use the development agent to create NotificationBell component with
real-time updates via WebSocket

# Step 3: API Development with Claude Code
# Prompt: "Create API routes for notifications following 5-layer architecture"
# Claude generates: Prisma schema, ORM functions, API routes, OpenAPI spec

# Step 4: Test Generation with Test Generator Agent
@repo Test generator agent: Create comprehensive tests for notification system

# Step 5: Security Audit with Security Audit Agent
@repo Security audit agent: Review notification API for vulnerabilities

# Step 6: Code Review with Code Review Agent
@repo Code review agent: Review all notification system changes

# Step 7: Rapid Iteration with Cursor
# Use Cursor AI chat for quick UI tweaks and styling adjustments