# Take control of your AI Agent by adding an AGENTS.md file

An AGENTS.md file is the custom ruleset for how you want your AI agent to behave. Anytime you provide a prompt, the agent references the AGENTS.md to ensure the response or action follows the ruleset before moving forward. It guarantees consistency and prevents you from fighting with the AI every time you enter a prompt.

While the file is written in <a href="https://www.markdownguide.org" target="_blank">Markdown</a>, you DO NOT need to be an engineer to use it. If you use AI for **any** purpose, you can add one to the root of your primary work directory on your computer and either symlink or hardlink to it from any other work directory and customize it for your own purposes (more on this in a moment).

If you do not want to write the instructions manually because you are not comfortable writing Markdown, you can prompt your agent with the rules you want to add, and it will add them in Markdown for you. If you are not a developer who works inside of an IDE and wish to manually customize the rules, then just open up the file in Notepad or another simple text editor, type out the instructions in Markdown, and save it with the `.md` extension.

For those of you using Claude, you can alternatively use a Claude.md to serve the same purpose; however, an AGENTS.md will be picked up by any LLM you are using, so I recommend using that instead. If you prefer to use Claude.md and are using the Claude Code app in your terminal, you can have Claude generate the default Claude.md by typing `/init` in the terminal inside of the root of your work folder. This will generate the baseline file that you can then customize. If you use the Claude desktop app, you can tell Claude to reference it in the project’s **Custom Instructions** sidebar; type: *“Always read and prioritize the style rules laid out in the attached Claude.md file.”*

If you work out of multiple project directories and want to manage all your instructions in a single file, you can ask Claude (or whatever LLM you use) to symlink each project to the root AGENTS.md file for you: “*Claude, I have added an Agents.md (or Claude.md) file to the current root directory with the instructions I want you to use moving forward. I need you to symlink that file to all of my project folders in this working directory.”*

Alternatively, if you do not like symlinks, you can place a blank AGENTS.md in the root of each project directory and add a hard link inside of it that points to the primary AGENTS.md in the project root. With this symlink or hard link in place, you will only need to edit the AGENTS.md in the project root, and the changes will apply to each project or working directory!

Note that in general, if you open your projects from the project root as your workspace, the agent should be able to reference the AGENTS file without needing the symlinks or agents files in each project; however, if you open the individual projects as the workspace root, you will need the hard link or symlink in place. To save yourself time moving forward, you can also add the instruction *“Whenever creating a new project directory for me, add a new AGENTS.md to it and link it to the source of truth Agents file for me.”*

For example:

```plaintext
/Projects  
  AGENTS.md <-- primary agents file with instructions (if you work out of this directory, you won't need an AGENTS.md in every project folder  
      /Project1  
      /Project2
```

If you are like me, you probably have an issue with the cumbersome and robotic language AI uses in its responses. Adding a *Personality & Communication* ruleset in your AGENTS.md is an excellent way to address this. While it will not perfectly humanize the response, it will at least be less verbose and stick to more common language.

This is mine:

```markdown
## Personality & Communication
- **Be direct:** State the primary answer or core conclusion in the very first sentence. Avoid introductory filler like "Sure, I can help with that" or "Here is the information."
- **Eliminate verbosity:** Keep sentences short and use the active voice.- **Maintain a natural, human tone:** Speak like a helpful, clear-headed peer. Avoid overly formal corporate jargon, rigid academic phrasing, or robotic disclaimers.
- Bold paths; bullets over walls of text.- If unclear what to build, ask one short question before coding.
```

When crafting your AGENTS file, try to keep your AGENTS file below 250 lines. Excessively long rule sets will create increased latency in the responses and burn more tokens. Keep it tight and actionable.

Below is my full, primary AGENTS.md as a Vue.js/TypeScript engineer. Feel free to copy as much of it as you think is relevant to your needs, or use it as a starter for your own stack.

Happy prompting!

````markdown
## Projects AGENTS.md (canonical)

Source of truth for `/Users/dannygibas/Projects`.

**Scope:** Greenfield stack rules apply to **new projects only**. Do not rewrite existing apps (styles, READMEs, aliases, structure) unless D asks. Vue rules → Vue apps. React apps → local patterns + shared sections (comms, secrets, change control, DoD).

**New apps:** Symlink this file as root `AGENTS.md` (`../AGENTS.md` or `../../AGENTS.md`). For public GitHub demos, a short pointer file is fine if a symlink looks messy.

---

## Personality & Communication

- **Be direct:** State the primary answer or core conclusion in the very first sentence. Avoid introductory filler like "Sure, I can help with that" or "Here is the information."
- **Eliminate verbosity:** Keep sentences short and use the active voice.
- **Maintain a natural, human tone:** Speak like a helpful, clear-headed peer. Avoid overly formal corporate jargon, rigid academic phrasing, or robotic disclaimers.
- Keep explanations under 3 sentences. Skip teaching standard APIs (`map`, `ref`, etc.) unless it prevents a hidden bug.
- Bold paths; bullets over walls of text.
- If unclear what to build, ask one short question before coding.

---

## Change Control

- **Stay on request:** Only what the latest ask requires. No drive-by cleanups, renames, restyles, or extra files unless D asks.
- Ask before behavior/API changes or refactors.
- In an already-approved file: typos, type fixes, and obvious bugs are OK without re-asking.
- Ask before touching vendor config, `.env` / mocks, or DB seeds.
- Match existing patterns; get approval before changing them.
- Never commit or push unless D asks.

---

## Secrets & Git

- Never commit secrets. Gitignore `.env` / `.env.*` (allow `.env.example`).
- Secrets only in local `.env` / `.env.local`.
- New projects: ship `.env.example` with `VITE_*` placeholders.

---

## New Project Layout

| Path                       | Purpose                |
| -------------------------- | ---------------------- |
| `src/components/`          | UI only                |
| `src/composables/`         | `use*` reactive logic  |
| `src/types/`               | Types / unions         |
| `src/stores/`              | Pinia — only if needed |
| `src/utils/` or `src/lib/` | Plain helpers          |
| `src/assets/`              | Imported assets        |

---

## Stack (new projects)

- TypeScript, strict null checks; prefer type files.
- **Tailwind v4** + `@tailwindcss/vite`. No vanilla/inline CSS unless a third-party lib needs it (ask first).
- Existing / a11y–API drills: match the repo (scoped CSS OK).
- Components = display; logic in composables.
- Native HTML + Tailwind first — ask before UI kits (Headless, Radix, Vuetify, etc.).
- Vue Router only when there is more than one real route.
- Ask before adding npm deps.
- Prefer `const` over `let`.
- API URLs from `import.meta.env.VITE_*` — never hardcode; never use `process.env` in Vite client code.
- New projects: configure `@` → `/src` in **vite.config + tsconfig**. Do not invent `@/` mid-edit in repos that lack it.

**Theme tokens:** Define in `@theme` / Tailwind config. Utilities OK if they map to tokens. **No raw hex in SFCs.**

```css
@theme {
  --color-background: #f7f7f7;
  --color-foreground: #1a1a1a;
  --color-border: #d4d4d4;
  --color-success: #15803d;
}
````