Setup Mistakes: Getting Started Wrong
Mistake 1: No rules file. The most common and most damaging mistake. A team adopts AI coding tools without creating a CLAUDE.md or equivalent. Every developer's AI: generates code using different conventions. The result: code reviews become convention enforcement sessions, the codebase becomes inconsistent, and the team concludes 'AI tools don't work for us.' The fix: spend 30 minutes writing a V1 rules file before the team starts using AI tools. The rules: transform the AI from a liability into an asset.
Mistake 2: Writing rules that are too vague. 'Write clean code' — what does this mean? The AI: interprets 'clean' differently in every context. 'Write good tests' — how many? What kind? What coverage? Vague rules: produce vague output. Effective rules are specific: 'Use named exports. Error handling uses Result<T, AppError>. Tests use Vitest with describe/it blocks. One assertion per test.' Specific rules: produce specific, consistent output.
Mistake 3: Copying someone else's rules without adaptation. A team copies a popular CLAUDE.md template from GitHub. The template: uses React, Jest, and Prisma. The team's project: uses Vue, Vitest, and Drizzle. The AI: generates code for the wrong framework. The fix: start with a template, then customize EVERY convention to match YOUR project. The template: saves time on structure. The customization: ensures accuracy. AI rule: 'Setup mistakes share a common cause: treating AI tool adoption as plug-and-play. AI tools without configuration: use generic defaults. AI tools with your specific rules: generate your specific code. The 30 minutes of setup: determines months of productivity.'
Usage Mistakes: Working With AI Incorrectly
Mistake 4: Accepting AI output without review. The AI generates a function. It looks right. The developer commits it without reading it carefully. The function: has a subtle bug (wrong comparison operator, missing edge case, incorrect null handling). The bug: reaches production. The lesson: AI output is a draft, not a final product. Review AI-generated code with the same rigor as human-written code. The AI: is fast and consistent, not infallible.
Mistake 5: Prompting with implementation details instead of intent. Developer prompt: 'Create a div with className flex gap-4 and map over items rendering a Card component.' The AI: creates exactly that (no added value). Better prompt: 'Create a responsive grid of product cards that shows price, image, and rating.' The AI: implements the intent using the project's conventions (from the rules), including responsive behavior, proper component patterns, and accessibility — all decisions that the developer didn't need to specify because the rules handle them.
Mistake 6: Not updating rules when conventions change. The team switches from Jest to Vitest. The CLAUDE.md: still says 'Use Jest for testing.' The AI: generates Jest tests. Developers: manually convert to Vitest after generation. The fix: update rules immediately when conventions change. Treat the rules file like documentation — keep it current. A stale rules file: worse than no rules file (because it generates confidently wrong code). AI rule: 'Usage mistakes share a pattern: treating the AI as either infallible (no review) or as a text editor (dictating implementation). The optimal approach: describe intent, let the AI use the rules, then review the output for correctness.'
Implementation prompt: 'Create a div with className flex gap-4 and map over items.' The AI: creates exactly what you said (a div with flex gap-4). You got a text editor, not an AI assistant. Intent prompt: 'Create a responsive product card grid with price and rating.' The AI: uses your project's rules to choose the layout pattern, component structure, responsive approach, and accessibility attributes. You got convention-compliant code without specifying implementation details. The rule: describe WHAT you want. Let the AI + rules decide HOW to build it.
Team Mistakes: Organizational Anti-Patterns
Mistake 7: Different team members using different AI tools without shared rules. Developer A uses Claude Code with CLAUDE.md. Developer B uses Cursor without .cursorrules. Developer C uses Copilot with no configuration. The codebase: a mix of three convention sets. The fix: create rules for ALL tools the team uses. If the team uses Claude Code and Cursor: maintain both CLAUDE.md and .cursorrules with the same conventions. RuleSync: solves this by synchronizing rules across tools.
Mistake 8: Not including AI rules in sprint planning. The tech lead creates CLAUDE.md as a side project — rushed, incomplete, never updated. The team: gets partial benefit. The fix: allocate sprint time for rule creation (initial: 2-4 story points), rule updates (per sprint: 0.5-1 story point), and rule review (quarterly: 2-3 story points). The investment: small. The return: consistent across every sprint.
Mistake 9: One person owns all the rules. The senior developer writes all the rules. Other team members: never read them, never update them, never suggest improvements. When the senior developer leaves: the rules become stale. The fix: shared ownership. Everyone on the team can propose rule changes. Rule changes: reviewed like code changes (PR with explanation). The rules: reflect the whole team's knowledge, not one person's preferences. AI rule: 'Team mistakes come from treating AI rules as an individual tool instead of a team asset. Rules should be: collectively owned, regularly updated, and allocated proper sprint time. A team's rule quality: reflects the team's investment in rules.'
One person writes all the rules. Nobody reviews them. The rules: reflect one person's preferences, not the team's conventions. When that person leaves: nobody understands the rationale behind the rules. The fix: treat rule changes like code changes. Rule update: submitted as a PR. PR description: explains the rationale (why this convention? what problem does it solve?). Team review: ensures everyone understands and agrees. The result: shared ownership, documented rationale, and rules that survive team changes.
Advanced Mistakes: Subtle Anti-Patterns
Mistake 10: Rules that are too restrictive. 'Every function must be under 10 lines. Every variable must use camelCase. Every file must have exactly one export.' Over-restrictive rules: force the AI into unnatural patterns. The AI: splits a naturally 15-line function into awkward helper functions to satisfy the rule. The code: technically compliant but harder to read. The fix: rules should express conventions, not micro-manage every line.
Mistake 11: Not testing rules against real prompts. A team writes rules. Nobody tests whether the AI actually follows them. Some rules: phrased ambiguously, causing the AI to interpret them differently than intended. The fix: test each rule by prompting the AI with a scenario that should trigger it. If the AI doesn't follow the rule: refine the wording until it does. Rule testing: 5 minutes per rule, done once.
Mistake 12: Ignoring AI suggestions that violate rules. The AI suggests a pattern that violates a rule — but the suggestion is actually better. The developer: forces the rule-compliant version. The fix: if the AI's suggestion is genuinely better, update the rule. Rules should evolve based on experience. A rule that consistently produces worse code than the AI's default: should be removed or revised. Mistake 13: Not leveraging rules for onboarding. New developer joins. Nobody tells them about CLAUDE.md. They use the AI without project context. The fix: include 'read CLAUDE.md' in the onboarding checklist. Mistake 14: Writing rules about tools instead of conventions. 'Use VS Code with the Prettier extension' — not an AI rule (the AI doesn't use VS Code). 'Format with 2-space indentation, single quotes, trailing commas' — this is an AI rule (the AI applies this to generated code). Mistake 15: Never measuring rule effectiveness. The team writes rules but never checks if review time decreased, if bug count changed, or if onboarding speed improved. Without measurement: you can't improve. The fix: track review time, bug count, and onboarding speed before and after rule adoption. AI rule: 'Advanced mistakes come from a static mindset about rules. Rules are living documents. They should be tested, measured, evolved, and sometimes retired. The best rule systems: improve continuously based on data and experience.'
'Every function must be under 10 lines.' The AI: encounters a naturally 15-line function (a switch statement with 6 cases). To satisfy the rule: splits it into 3 functions (processSmall, processMedium, processLarge) that are only called once and add indirection without benefit. The code: technically compliant, harder to read, more complex. Over-restrictive rules: force the AI into unnatural patterns. Effective rules: express conventions at the right abstraction level. 'Prefer small, focused functions' (guidance) vs 'Every function under 10 lines' (micro-management). The difference: significant.
AI Coding Mistakes Quick Reference
Quick reference of 15 AI coding mistakes and their fixes.
- Mistake 1: No rules file — Fix: spend 30 minutes on V1 before team adoption
- Mistake 2: Vague rules — Fix: be specific (name the pattern, framework, convention)
- Mistake 3: Copied rules — Fix: customize every convention to your actual project
- Mistake 4: No review — Fix: review AI output with the same rigor as human code
- Mistake 5: Implementation prompts — Fix: describe intent, let rules handle implementation
- Mistake 6: Stale rules — Fix: update rules immediately when conventions change
- Mistake 7: Inconsistent tools — Fix: maintain rules for ALL AI tools the team uses
- Mistake 8: No sprint time — Fix: allocate story points for rule creation and updates
- Mistake 9: Single owner — Fix: shared ownership, rule changes reviewed as PRs
- Mistake 10: Over-restrictive — Fix: express conventions, don't micro-manage every line
- Mistake 11: Untested rules — Fix: test each rule with a real prompt (5 min per rule)
- Mistake 12: Ignoring good suggestions — Fix: update rules when AI finds better patterns
- Mistake 13: No onboarding — Fix: include CLAUDE.md in the onboarding checklist
- Mistake 14: Tool rules not conventions — Fix: write rules about code output, not editor setup
- Mistake 15: No measurement — Fix: track review time, bugs, onboarding speed