title: "Agent Ignores Project Conventions" last_updated: 2026-03-21 status: proven difficulty: beginner prerequisites: [02-project-memory]

Problem: Agent Ignores Project Conventions

Symptoms

  • Agent uses var when you require const/let
  • Agent creates files in wrong directories
  • Agent uses a different testing framework than your project
  • Agent doesn't follow your naming conventions

Common Causes

  1. No CLAUDE.md / AGENTS.md — The agent has no way to know your conventions without project memory.
  2. Conventions are too vague — "Follow best practices" means nothing. "Use arrow functions, not function declarations" is actionable.
  3. CLAUDE.md is too long — If your config file is 200+ lines, important instructions get diluted.
  4. Convention conflicts with codebase — If your existing code doesn't follow the conventions you wrote, the agent may follow the code patterns instead.

Solutions

For Cause 1: Create Project Memory

Create a CLAUDE.md or AGENTS.md with your conventions. See Starter Template.

For Cause 2: Be Specific

Replace vague instructions with precise ones:

# Bad
- Follow good coding practices

# Good
- Use `const` by default, `let` only when reassignment is needed, never `var`
- Name files in kebab-case: `user-profile.ts`, not `userProfile.ts`

For Cause 3: Trim Your Config

Keep CLAUDE.md under 80 lines. Move detailed documentation elsewhere and keep only actionable instructions in the config.

For Cause 4: Fix the Codebase First

If your existing code uses inconsistent patterns, fix the most visible files first. The agent learns from what it reads.

Prevention

  • Start with the Starter CLAUDE.md on day one
  • Add one convention each time you have to correct the agent manually
  • Use the "Convention Test" exercise from Module 02