I’ve been using tools like ChatGPT Codex, Claude Code, and Cursor for a while now for “vibe coding” some tools on my home server. (I don’t think it’s technically vibe coding if you know and care about the architecture, but that term works well enough for now). For simple, custom web services, it’s pretty easy to have AI cook something up without needing to write any code yourself.
You do need to have some process in place to make sure you’re asking for what you want though. One essential tool in this is the Agents.md file, a series of rules for your AI agent to follow. Most AI coding systems support this now, though some still seem to recognize it a little better if you have a slightly different file name or location (like, ~/.codex/AGENTS.md rather than project root).
Mine is constantly evolving, but I thought it was worth sharing. I’ve found a lot of value in reviewing others’ agent instructions. Some of these guidelines are being adopted by the agents coding systems in their system instructions, like avoiding emojis and em dashes. But I’m also constantly finding new tricks to add to it.
Some sources of these instructions include my own agentic engineering experience (once I notice I’m giving the same feedback multiple times, I document it in the Agents.md file), the book Vibe Coding, Simon Willison’s Agentic Engineering Patterns (and his blog), and the AI for Humans podcast.
Here’s the current version I’m using as a starting point for most projects:
# **AGENTS.md**
Defines how AI coding agents (OpenAI Codex, Claude Code, Cursor, etc.) should operate in this repository.
Supplements `README.md` (for humans) and nested `AGENTS.md` files (for scoped behavior).
---
## **PROJECT**
**Project Name:**
*e.g., Home Dashboard*
**Description:**
*A concise 2-3 sentence summary of the project's purpose. Include if single user and local or if plan to share online. *
**Technical Overview:**
* Core languages and frameworks
* CI/CD system
* Deployment target(s)
* Hosting environment: Azure / Docker / VM / etc.
---
## **GUIDELINES**
### **Core Principles**
1. **Keep it modular and simple.**
* Small, focused functions/files; minimal deps; readability first. Leave room for future expansion.
2. **Preserve existing functionality.**
* Modify only when directed; additive or reparative work.
* Guard against regressions; validate existing behavior.
* Lean on regression tests to prevent drift; extend coverage for critical paths.
3. **Mobile-first and observable.**
* Design mobile-first, verify desktop.
* Ship a favicon in the HTML head.
* Surface build/version in the UI and keep it in sync with release metadata.
4. **Log from day one.**
* Structured, meaningful logging for errors/warnings/key actions from the start.
* If appropriate, put a page to see logs in the UI.
* Create a logging endpoint you (the AI agent) can use to retrieve logs for debugging.
5. **Refine in passes.**
* Multiple passes for quality/readability; flag non-standard patterns and suggest standardization/accessibility for AI readability.
6. **Maintain documentation and context.**
* Each file starts with a short overview.
* Keep `README.md`, nested `AGENTS.md`, and `TODO`/`notes.md` current.
* **At any point, I should be able to start a new AI conversation and not lose context.**
7. **Ask questions early.**
* Don't guess; request clarification early.
8. **Plan first, code second.**
* Outline steps and confirm before coding.
9. **Limit sprawl and keep commits focused.**
* Keep PRs atomic and on-topic.
10. **Use red / green test-driven development.**
* Write and run tests *before* coding; ensure coverage for new changes. Protect new features with thorough regression tests and add any other type of tests necessary for stable, production deployments.
11. **Use AI-readable structure.**
* Clear directories, consistent naming, and Markdown/YAML configs.
---
### **Git & Commit Rules**
* IMPORTANT: You - the AI agent - handle commits and syncs after you finish every task.
* Follow **Chris Beams' commit style** ([https://cbea.ms/git-commit](https://cbea.ms/git-commit)):
* Imperative mood ("Add feature X").
* Explain *what* and *why* in the body.
**Example:**
```
feat(auth): add Azure AD token caching
Ensures cached tokens are reused across requests to reduce latency.
Follows Microsoft's best practice for cloud API throttling.
```
---
### **General Notes**
* No emojis in code, logs, or terminal output.
* Minimal dependencies; use standard libraries when possible.
* Verify licenses before adding external packages.
* Other than the Project section, do not update Agents.md. It must stay short so critical rules can be remembered. Create other documentation files when needed.
---
## **OPTIONAL CONTEXT**
### **Homelab Projects**
* Developed in **VSCode** using **Claude Code** and **OpenAI Codex** (Windows).
* Deployed as **Docker containers** on **Ubuntu VM**.
* Request my template docker compose file if missing it. Files will be named like projectname.yml
* Containers built from Git repo during deployment - do not change to local build context. Docker server is different host from development machine; docker is not accessible for the AI agent.
* Homelab is available only on local network.
* Preferred stack: Python, Flask and / or FastAPI, Pico.css (add to repo, not from CDN), SQLite. Bootstrap icons (or backup, Phosphor icons if needed) when visuals are needed rather than emojis. Import to project, don't load from cdn.
* Source control: **Gitea** with automated testing and container redeploys planned.
---
## **FOR LATER PASSES**
Schedule refinement passes for:
* Conciseness and readability
* Simplicity and modularity
* Error handling, logging, and static analysis
* Broader test coverage
* CAREFULLY clean up outdated or unused files
* security review
