Why Your AI Generates Crap Code - And How to Fix It

How AI Coding Agents End Up Producing “Crap” Code (and the Fix)

The video explains why AI coding agents often generate low-quality (“crap”) code and how to improve results by properly configuring the context the agent receives—especially your agents.md / claude.md file, and by offloading details into documentation and skills.

---

How AI Context Is Assembled (Main Idea)

When you send a prompt to an AI, it usually receives more than just your message. It may also include:

• System prompt (typically not user-configurable)
• agents.md (or Claude.md for Claude code; conceptually the same)
• Skills (optional; loaded when needed)
• Documentation / codebase context (if configured/available)
• Your actual query / prompt

Because agents.md is included with every request, mistakes there—or overly bloated content—can “poison” all outputs.

---

What to Fix: agents.md (or claude.md) Quality

1) Keep agents.md Small (Avoid Token / Context Bloat)

The instructor criticizes large, ever-growing agents.md examples (from Codex, Airflow, VS Code) because they tend to be:

• Extremely long “kitchen-sink” lists
• Full of rules that won’t apply to most requests
• Duplicated style/rule content
• Wasteful—consuming tokens and reducing output quality as context grows (quality drops noticeably well before extremely large context windows)

2) Replace Large Rule Blocks with Links to Smaller Docs

A recommended approach:

• Move detailed conventions (CSS, API, testing, terminal style, etc.) into separate markdown files
• Keep agents.md as a compact index: short descriptions + links to those files

This preserves agent flexibility without turning agents.md into a massive context dump.

3) Remove “Getting Started / Setup” Sections

agents.md should not be a project onboarding guide (install dependencies, etc.). Instead:

• Use a 1–2 sentence description of the project’s essence
• Only call out non-standard project details (e.g., “use PNPM instead of npm”, custom scripts)
• Link out to other docs for everything else

4) Track Errors Incrementally (Don’t Preemptively Overwrite Rules)

Rather than trying to anticipate all future mistakes:

• Observe specific failure modes (e.g., strange TypeScript behavior)
• Add targeted rules to the appropriate doc/section only when you see real issues

---

Claude-Specific Note: Keep claude.md Aligned with agents.md

When rules exist in one file but not the other, inconsistencies can cause problems.

Best practice shown:

• Make claude.md a symbolic link to agents.md, so they always match.

OS-specific examples:

• Linux/Mac: ln -s ...
• Windows: mklink ... (may require admin privileges)

---

Monorepo Strategy: Multiple agents.md Files

For monorepos (multiple apps/packages in one repo), use:

• A root agents.md for general rules
• Folder-level agents.md files for package-specific conventions (e.g., web vs API)

When running the agent:

• The AI loads agents.md based on the folder you run it from Example: running in app/api loads the root rules + API-specific instructions

This avoids one huge agent file mixing unrelated framework/language rules (e.g., Python backend rules with TypeScript/React frontend rules).

---

Skills: When to Use Them vs agents.md

Purpose

Skills are markdown modules loaded only for specific tasks. They prevent stuffing every capability into agents.md, reducing context clutter.

Installation and Discovery

• Install with: npx skills add <skill-link>
• Skills can be found on: skills.sh

How They’re Used

• Each skill includes a skill.md with a name/description
• When the agent needs something, it selects the relevant skill(s) and loads the detailed markdown

Key Guidance: One-Time vs General Knowledge

• Use agents.md / docs for general rules that apply often (TypeScript conventions, repo structure)
• Use skills for infrequent/specific tasks (e.g., authentication), so they load only when needed

Manual Invocation

Skills can be summoned by the user (example mentioned):

• typing /skill in supported editors/tools
• selecting a skill (e.g., “Algorithmic Art”) to guide the AI

---

Topics Not Deeply Covered

The speaker explicitly says they won’t focus on the app’s actual codebase content. Instead, the focus is on:

• configuration files
• context strategy
• how these affect the AI’s ability to generate code

---

Main Speaker / Sources

• Speaker: Kyle (Web Dev Simplified)
• References/examples mentioned:
  • OpenAI / Codex
  • Airflow
  • Visual Studio Code (as “terrible examples” of agents.md)
  • Tooling like Claude Code, Pi, and Gemini (as analogous agent-config naming patterns)