How I Document Agent Instructions

I shared a short Twitter exchange with @embirico (Codex lead at OpenAI) about my approach to documenting instructions for coding agents.

Alexander Embiricos

@embirico

·Follow

This was a useful & interesting read. Anyone else have AGENTS.md setups they'd want to share?

Brennan McEachran 👨‍🚀

@i_am_brennan

Took way to long to get it in a gist. gist.github.com/brennanmceachr… It's basically a wiki of how to code in various parts of the app. I think have different short specific agents.md files for codex, gemini, vs code, cursor, etc, which direct the agent to read the

3:23 PM · Jul 17, 2025

19

Reply

Copy link

Read 2 replies

After pulling everything together for him, it felt worthwhile to post the same info here so others can reference it.

Below is the full set of rules I keep in my repo. Each file lives in the gist linked in the discussion, but I've inlined them here for convenience.

1---
2filepath: "AGENTS.md"
3---
4# AGENT Guidelines
5
6- Before making changes, read `.instructions/general.instructions.md` and any relevant instructions inside `.instructions/apps` or `.instructions/packages` for the files you plan to modify.
7- Keep TypeScript strictly typed. Do **not** use `@ts-ignore` or ESLint disable comments.
8- Always run `pnpm typecheck` to ensure your code is working. This also builds any needed deps. So do this anytime you cross a package boundary.
9- Use `pnpm lint` to check for linting errors and code style.
10- Use `pnpm format -w` to format all packages before committing.
11- The GitHub PR workflow will run `pnpm typecheck`, `pnpm lint`, and `pnpm format` to ensure code quality and will not allow merging if there are issues.
12

Feel free to pull these into your own repo or modify them for your stack. The gist with these files is available here.

Why bother?

• Consistency: I run on the latest versions of many deps. Explicit instructions keep models from assuming outdated patterns.
• Speed: Agents spend less time hunting through files when they know exactly where to look.
• Collaboration: Others can jump into my repo and see the same guidance the agents follow.

I'm now nudging the community to share their own rules. I started a discussion on the T3 Turbo repo if you want to chime in.

Parting Thoughts

This short exchange reminded me that good documentation isn't just for humans. Agents need guidance, too. If you haven't written rules for your repo yet, now's a great time to start.