Skip to content
Pip Decks AI Building Bootcamp

Markdown Files & agents.md

Another thing that comes up a lot in AI coding are markdown files (.md).

A markdown file is just a file format for plain text with some formatting (headers, lists, etc). If you use PowerPoint then you’ll know that when you export a presentation, it’ll be in a PPTX format. If you export one on Mac, it’ll be a .keynote format. If you use Excel, it’ll be a .xlsx file, but if you use Google Sheets, it’ll be a .csv or something else.

These markdown files allow you to give your agent custom instructions beyond the system prompt. Agents look for an AGENTS.md file (except Claude looks for CLAUDE.md).

In that file, you could have a prompt that says, “I’m not very technical at all, so anytime you’re talking about code, please explain exactly what it is at all times,” or, “Explain it to me like I’m five.” You’ll see a big difference in output between not having that instruction and having it.

What Developers Put in agents.md

Section titled “What Developers Put in agents.md”

Developers often put a lot of different things in here, like:

  • “This is the tech stack for this project”
  • “These are the key files to look at”
  • “These are the commands you need to use to run this particular project”

And it’s all hierarchical, where the closest markdown file to what you’re working on will be read first before the preceding one…

my-project/
├── AGENTS.md              ← Root instructions (read last)
├── src/
│   ├── AGENTS.md          ← Source-specific rules (read second)
│   └── components/
│       ├── AGENTS.md      ← Component rules (read first!)
│       └── Button.tsx

When editing Button.tsx, the agent reads the closest AGENTS.md first (components/), then works its way up to the root (home).

The Hierarchy in Practice

Section titled “The Hierarchy in Practice”

This hierarchical approach means you can have:

  • Project-wide rules at the root level that apply everywhere
  • Folder-specific rules that override or add to the root rules
  • Component-specific rules for very targeted instructions

The agent combines all of these, with the most specific (closest) file taking priority when there’s a conflict.

Section titled “Related Resources”