Skip to content
Cortex TMS Logo Cortex TMS Logo Cortex TMS

AI Agent Issues

This guide helps you diagnose and fix problems with AI coding agents (Claude Code, GitHub Copilot, and Cursor) when used with Cortex TMS. Whether your AI agent is not reading documentation files, generating code that violates patterns, or experiencing context window issues, this page provides systematic solutions.

Quick Diagnostic by AI Agent

Claude Code Issues

Common symptoms:

  • Not reading CLAUDE.md
  • Ignoring operational workflows
  • File access permission errors
  • Context window exceeded

Jump to Claude Code →

GitHub Copilot Issues

Common symptoms:

  • Not reading .github/copilot-instructions.md
  • Suggestions violate documented patterns
  • 100-line limit exceeded
  • Chat not referencing instructions

Jump to Copilot →

Cursor Issues

Common symptoms:

  • .cursorrules not detected
  • Symlink not working (Windows)
  • Chat not using custom rules
  • Composer ignores patterns

Jump to Cursor →

General AI Problems

Common symptoms:

  • AI violates PATTERNS.md conventions
  • Stale context (reads old files)
  • Token limits hit
  • Inconsistent suggestions

Jump to General →

Claude Code Troubleshooting

Issue: Claude Code Not Reading CLAUDE.md

Symptoms

Claude Code generates code that doesn’t follow documented workflows:

  • Doesn’t create feature branches before code changes
  • Doesn’t read NEXT-TASKS.md to understand current objectives
  • Doesn’t follow patterns from docs/core/PATTERNS.md
  • Doesn’t run post-task validation

Cause

Cause 1: CLAUDE.md doesn’t exist or is in wrong location

Cause 2: CLAUDE.md has file permission issues

Cause 3: Claude Code is reading a cached/stale version

Solution

Step 1: Check CLAUDE.md exists in project root

Terminal window
ls -la CLAUDE.md

Expected output:

-rw-r--r--  1 user  staff  2048 Jan 15 10:30 CLAUDE.md

If missing:

Terminal window
# Regenerate with cortex-tms
cortex-tms init --force


# Or restore from templates
cortex-tms validate --fix

Step 2: Verify file encoding

Terminal window
file CLAUDE.md

Expected output:

CLAUDE.md: UTF-8 Unicode text

If wrong encoding:

Terminal window
# Convert to UTF-8
iconv -f ISO-8859-1 -t UTF-8 CLAUDE.md -o CLAUDE.md.utf8
mv CLAUDE.md.utf8 CLAUDE.md

Step 3: Test with explicit reference

Ask Claude Code:

“Read CLAUDE.md and summarize the operational loop”

Expected: Claude should read and summarize the file.

If Claude can’t read it: File permissions or Claude Code bug.

Issue: Claude Code Ignoring Patterns

Symptoms

Claude generates code that violates documented conventions:

  • Uses localStorage for tokens (despite PATTERNS.md forbidding it)
  • Uses HS256 instead of RS256 for JWT
  • Doesn’t follow naming conventions from PATTERNS.md
  • Ignores error handling patterns

Cause

Cause 1: PATTERNS.md is too large (exceeds Claude’s context)

Cause 2: Patterns are vague (descriptions without examples)

Cause 3: CLAUDE.md doesn’t reference PATTERNS.md

Solution

Claude learns better from examples than descriptions.

Before (vague):

## Authentication Pattern


Use RS256 JWT tokens with httpOnly cookies. Tokens expire in 15 minutes.

After (concrete example):

## Authentication Pattern


**Canonical Example**: `src/middleware/auth.middleware.ts`


**Always use this exact pattern:**


` ` `typescript
import { sign, verify } from 'jsonwebtoken';
import { readFileSync } from 'fs';


// Load RS256 keys
const privateKey = readFileSync('./keys/private.pem');
const publicKey = readFileSync('./keys/public.pem');


// Generate access token (15 min expiry)
export function generateAccessToken(userId: string) {
  return sign(
    { userId, type: 'access' },
    privateKey,
    { algorithm: 'RS256', expiresIn: '15m' }
  );
}


// Store in httpOnly cookie (NEVER localStorage)
export function setAuthCookie(res: Response, token: string) {
  res.cookie('accessToken', token, {
    httpOnly: true,      // ✅ Prevents XSS
    secure: true,        // ✅ HTTPS only
    sameSite: 'strict',  // ✅ CSRF protection
    maxAge: 15 * 60 * 1000, // 15 minutes
  });
}


// ❌ NEVER DO THIS
// localStorage.setItem('token', token);
` ` `


**Key rules:**


- ✅ Use RS256 (asymmetric) for tokens
- ✅ Store in httpOnly cookies
- ✅ 15-minute expiry for access tokens
- ❌ Never use HS256 (symmetric)
- ❌ Never use localStorage (XSS vulnerable)

Now Claude can copy the exact implementation.

Issue: Context Window Exceeded

Symptoms

Claude Code returns errors:

Error: Context window exceeded. Please reduce the amount of context.

Or Claude stops mid-response:

I apologize, but I've reached the context limit. Could you please...

Cause

Claude Code has a context window limit (200k tokens ≈ 150k words). Large codebases or very long files can exceed this limit.

Solution

Instead of asking Claude to read all files, use @file to specify exact files:

Instead of:

“Review the entire codebase and implement authentication”

Say:

“@file src/middleware/auth.middleware.ts Implement authentication following the pattern in this file”

This limits context to only the specified file.

GitHub Copilot Troubleshooting

Issue: Copilot Not Reading Instructions

Symptoms

Copilot suggestions ignore project conventions:

  • Suggests localStorage for tokens (despite copilot-instructions.md forbidding it)
  • Ignores naming conventions
  • Doesn’t follow documented patterns
  • Chat responses don’t reference instructions

Cause

Cause 1: .github/copilot-instructions.md doesn’t exist

Cause 2: File exceeds 100-line limit (Copilot’s hard limit)

Cause 3: VS Code hasn’t reloaded the file

Solution

Step 1: Check file exists

Terminal window
ls -la .github/copilot-instructions.md

If missing:

Terminal window
# Create directory
mkdir -p .github


# Generate with cortex-tms
cortex-tms init --force


# Or create manually
cat > .github/copilot-instructions.md <<'EOF'
# GitHub Copilot Instructions


See `CLAUDE.md` for full project conventions.


## Critical Rules


- Never commit secrets (API keys, passwords)
- Use RS256 JWT tokens (not HS256)
- Store tokens in httpOnly cookies (not localStorage)


## Tech Stack


- TypeScript (strict mode)
- Express.js
- Jest for testing


## Quick Reference


- Patterns: `docs/core/PATTERNS.md`
- Tasks: `NEXT-TASKS.md`
EOF

Step 2: Verify file is under 100 lines

Terminal window
wc -l .github/copilot-instructions.md

Expected:

68 .github/copilot-instructions.md

If over 100 lines: Copilot will ignore the file.

Issue: Copilot Violates Security Rules

Symptoms

Copilot suggests code that violates documented security rules:

  • Suggests localStorage.setItem('token', ...) despite instructions forbidding it
  • Suggests HS256 tokens instead of RS256
  • Suggests committing secrets (API keys in code)

Cause

Cause 1: Security rules are buried in the middle of copilot-instructions.md

Cause 2: Rules are stated positively (what TO do) instead of negatively (what NOT to do)

Cause 3: Copilot prioritizes code patterns over documentation

Solution

Copilot prioritizes early content. Put critical rules first:

Before:

# GitHub Copilot Instructions


## Tech Stack


TypeScript, Express.js, Jest


## Coding Style


Use camelCase for variables...


## Security Rules


Never commit secrets...

After:

# GitHub Copilot Instructions


## Critical Rules (Security)


**NEVER**:
- Store tokens in localStorage → Use httpOnly cookies
- Use HS256 for JWT → Use RS256
- Commit secrets (API keys, passwords) → Use .env


## Tech Stack


TypeScript, Express.js, Jest


## Coding Style


Use camelCase for variables...

Issue: Copilot Inline Suggestions Ignore Patterns

Symptoms

Copilot inline suggestions don’t match project conventions:

  • Variable names use wrong casing (snake_case instead of camelCase)
  • Function structure doesn’t match canonical examples
  • Import statements use wrong paths (relative instead of aliases)

Cause

Copilot inline suggestions use a smaller context window than chat. They prioritize:

  1. Current file content
  2. Recently opened files
  3. copilot-instructions.md (if under 100 lines)

Solution

Before coding, open canonical example files:

Step 1: Open reference files

Terminal window
# Open canonical service
code src/services/tasks.service.ts


# Open canonical controller
code src/controllers/tasks.controller.ts


# Open canonical test
code src/services/tasks.service.test.ts

Step 2: Start coding in new file

Copilot now has examples in context and will suggest matching patterns.

Example:

// In src/services/users.service.ts
// Type: export class UserService


// Copilot suggests (matching tasks.service.ts pattern):
export class UserService {
  constructor(private db: Database) {}


  async getById(id: string): Promise<User> {
    const user = await this.db.query.users.findFirst({
      where: eq(users.id, id)
    });


    if (!user) {
      throw new AppError('User not found', 404);
    }


    return user;
  }
}

Copilot matched the structure from tasks.service.ts.

Cursor Troubleshooting

Issue: .cursorrules Not Detected

Symptoms

Cursor doesn’t reference custom rules:

  • Chat responses don’t mention project conventions
  • Code generations violate documented patterns
  • Cmd+K edits ignore .cursorrules

Cause

Cause 1: .cursorrules file doesn’t exist

Cause 2: .cursorrules is a broken symlink (Windows)

Cause 3: Cursor settings disabled custom rules

Solution

Option 1: Copy from CLAUDE.md

Terminal window
cp CLAUDE.md .cursorrules
git add .cursorrules

Option 2: Create symlink (macOS/Linux)

Terminal window
ln -s CLAUDE.md .cursorrules
git add .cursorrules

Option 3: Create custom file

Terminal window
cat > .cursorrules <<'EOF'
# Cursor Rules


See `CLAUDE.md` for full conventions.


## Tech Stack


- TypeScript (strict mode)
- Express.js
- PostgreSQL + Drizzle ORM
- Jest + Playwright


## Critical Rules


- Never commit secrets
- Use RS256 JWT (not HS256)
- Store tokens in httpOnly cookies (not localStorage)


## Cursor Workflows


**Multi-File Edits**: Use Cmd+K for single-file, Chat for multi-file


**Pattern Application**: Reference canonical files:
- Service: `src/services/tasks.service.ts`
- Controller: `src/controllers/tasks.controller.ts`


## Quick Commands


- Test: `npm test`
- Lint: `npm run lint`
- Dev: `npm run dev`
EOF

Issue: Cursor Composer Ignores Patterns

Symptoms

Cursor Composer applies multi-file changes that violate patterns:

  • Refactoring doesn’t follow documented conventions
  • Generated code uses wrong naming conventions
  • Imports use wrong paths

Cause

Cursor Composer uses a broad context but may miss specific pattern files if not referenced explicitly.

Solution

When using Composer, reference pattern files:

Instead of:

“Refactor all services to use dependency injection”

Say:

“Refactor all services to use dependency injection following the pattern in src/services/tasks.service.ts. Inject database via constructor, use Drizzle query builder, throw AppError for errors.”

This ensures Composer reads the canonical example.

General AI Agent Issues

Issue: AI Violates PATTERNS.md Conventions

Symptoms

All AI agents (Claude Code, Copilot, Cursor) generate code that violates documented patterns:

  • Inconsistent naming conventions
  • Wrong error handling approach
  • Incorrect architectural decisions

Cause

Cause 1: PATTERNS.md is too abstract (no concrete examples)

Cause 2: Patterns conflict with existing code

Cause 3: Patterns not enforced by linting

Solution

Before (abstract):

## Error Handling


Use a custom error class with HTTP status codes.

After (concrete):

## Error Handling


**Canonical Example**: `src/errors/AppError.ts`


**Always use this exact pattern:**


` ` `typescript
// src/errors/AppError.ts
export class AppError extends Error {
  constructor(
    message: string,
    public statusCode: number = 500,
    public isOperational: boolean = true
  ) {
    super(message);
    this.name = 'AppError';
    Error.captureStackTrace(this, this.constructor);
  }
}


// Usage in services:
export class UserService {
  async getById(id: string): Promise<User> {
    const user = await this.db.query.users.findFirst({
      where: eq(users.id, id)
    });


    if (!user) {
      // ✅ Throw AppError with 404 status
      throw new AppError('User not found', 404);
    }


    return user;
  }
}
` ` `


**❌ Never do this:**


` ` `typescript
// Bad: Generic Error without status code
throw new Error('User not found');


// Bad: Returning null instead of throwing
return null;
` ` `

AI agents can now copy the exact implementation.

Issue: Stale Context (AI Reading Old Files)

Symptoms

AI agents reference old code that no longer exists:

  • Claude suggests using a deleted function
  • Copilot autocompletes with old variable names
  • Cursor references deprecated APIs

Cause

AI agents cache file contents and may not pick up recent changes.

Solution

Claude Code:

Terminal window
# Exit and restart
exit
claude-code .

GitHub Copilot:

Cmd+Shift+P → "Reload Window"

Cursor:

Cmd+Shift+P → "Reload Window"

Issue: Token Limits Hit

Symptoms

AI agents fail with token limit errors:

  • Claude: “Context window exceeded”
  • Copilot: “Request too large”
  • Cursor: “Reached token limit”

Cause

Large files, long conversations, or many files in context exceed AI token limits.

Solution

Terminal window
# Check file sizes
wc -l **/*.md


# Archive large files
cortex-tms validate --fix

AI Agent Best Practices

1. Keep Documentation Concise

  • CLAUDE.md: under 500 lines
  • copilot-instructions.md: under 100 lines
  • PATTERNS.md: under 500 lines per file

2. Use Canonical Examples

Show concrete code examples, not abstract descriptions. AI learns by copying.

3. Security Rules First

Put critical security rules at the top of instruction files. AI prioritizes early content.

4. Reference Files Explicitly

In NEXT-TASKS.md, reference specific pattern files. Don’t make AI search.

5. Validate AI Output

Always review AI-generated code. Run tests and linting before committing.

6. Update Docs When AI Fails

When AI violates a pattern, update documentation to be more explicit.

Improving AI Alignment

Step 1: Test AI with Sample Tasks

After setting up Cortex TMS, test each AI agent:

Claude Code:

“Read NEXT-TASKS.md and CLAUDE.md, then summarize the current sprint goal and operational workflow”

GitHub Copilot:

Open a new .ts file and type:

// Create a new service class following our pattern

Verify Copilot suggests code matching your patterns.

Cursor:

In Cursor Chat:

“@Codebase What’s our authentication pattern?”

Verify Cursor references docs/core/PATTERNS.md.

Step 2: Fix Documentation Gaps

When AI makes mistakes, improve docs:

AI mistake: Uses localStorage for tokens

Fix: Add to copilot-instructions.md:

## Critical Rules


**NEVER store tokens in localStorage** → Use httpOnly cookies


❌ Bad:
` ` `typescript
localStorage.setItem('token', token);
` ` `


✅ Good:
` ` `typescript
res.cookie('token', token, { httpOnly: true });
` ` `

Step 3: Iterate and Refine

AI alignment is iterative:

  1. AI generates code → 2. Review for violations → 3. Update docs → 4. Test again

After 3-5 iterations, AI will consistently follow your patterns.

Next Steps

Now that you understand AI agent troubleshooting: