The Agents.md Cookbook

Preface

1. Who this is for
2. What you will learn
3. The honesty note
4. The labels
5. The running examples
6. How to use this book
7. What you need before starting
8. Owning the file
9. Series note
10. One last thing

What a Rules File Is, and What It Is Not

1. The problem it solves
2. A small example
3. How an agent uses it
4. The three layers of instruction
5. What a rules file is not
6. What it can do
7. What it cannot do
8. Size and focus
9. When you do not need one
10. The name of the file
11. One session, in slow motion
12. Checklist

Anatomy of a Good Rules File

1. Project overview
2. Commands
3. Structure
4. Conventions
5. Boundaries
6. Testing
7. Security
8. Definition of done
9. A complete skeleton with all eight blocks
10. Why the order matters, in general terms
11. Reading an existing file against this anatomy
12. A summary of the eight blocks
13. When the anatomy fights your project
14. Checklist

Writing Rules an Agent Can Follow

1. Specific beats vague
2. Positive and negative rules
3. Show, don’t tell
4. Priorities, and how to make conflicts resolve safely
5. Avoiding contradictions
6. Keep it short
7. Tone: imperative, present tense
8. Writing for two readers at once
9. An exercise: your first three rules
10. Rewrite stress test
11. The three-fate rule
12. Checklist

Testing Your Rules

1. The before-and-after method
2. What to measure
3. The log
4. Reading results: the four verdicts
5. When a rule should be removed
6. How often to test
7. The test, from start to finish
8. When A and B are both bad
9. What testing cannot promise
10. What to record when you test
11. Checklist

Web App Starter

1. Goal and when to use it
2. Ingredients
3. The rules file
4. Why each rule is there
5. How to test it
6. Common mistakes and variations
7. Growing the file after week one
8. Checklist

API and Backend Services

1. Goal and when to use it
2. Ingredients
3. The rules file
4. Why each rule is there
5. How to test it
6. Common mistakes and variations
7. Reading an agent endpoint diff in sixty seconds
8. Checklist

Mobile App Projects (Flutter Style)

1. Goal and when to use it
2. Ingredients
3. The rules file
4. Why each rule is there
5. The three decisions this file makes for you
6. How to test it
7. Common mistakes and variations
8. Checklist

Python Scripts and Data Projects

1. Goal and when to use it
2. Ingredients
3. The rules file
4. Why each rule is there
5. How to test it
6. Common mistakes and variations
7. A worked example: the expenses summary
8. Checklist

Education and School Tools

1. Goal and when to use it
2. Ingredients
3. The rules file
4. Why each rule is there
5. How to test it
6. Common mistakes and variations
7. Checklist

Finance and Data Apps

1. Goal and when to use it
2. Ingredients
3. The rules file
4. Why each rule is there
5. How to test it
6. Common mistakes and variations
7. Checklist

Database and Migration Safety

1. Goal and when to use it
2. Ingredients
3. The rules file
4. Why each rule is there
5. How to test it
6. Common mistakes and variations
7. Checklist

Security Guardrails

1. Goal and when to use it
2. Ingredients
3. The rules file
4. Why each rule is there
5. How to test it
6. Common mistakes and variations
7. Checklist

Testing and Review Rules

1. Goal and when to use it
2. Ingredients
3. The rules file
4. Why each rule is there
5. Why this recipe is short on purpose
6. How to test it
7. Common mistakes and variations
8. Checklist

Git and Workflow Rules

1. Goal and when to use it
2. Ingredients
3. The rules file
4. Why each rule is there
5. How to test it
6. Reading the commits, not just the diff
7. Common mistakes and variations
8. Checklist

Documentation and Handover Rules

1. Goal and when to use it
2. Ingredients
3. The rules file
4. Why each rule is there
5. How to test it
6. Common mistakes and variations
7. A release note that works, in eight lines
8. Checklist

Larger Projects and Teams

1. Goal and when to use it
2. Ingredients
3. The rules file - root (shared/global only)
4. The rules file - one package (local rules only)
5. Why each rule is there
6. Team rules, in brief
7. How to test it
8. Common mistakes and variations
9. Checklist

Maintaining Your Rules File

1. Why maintenance matters
2. The two triggers for a review
3. The review routine, twenty minutes
4. The pruning list
5. Rule debt
6. Versioning the file cheaply
7. Choosing to rewrite from scratch
8. After tool and model changes
9. What to expect when the file is healthy
10. Expanding from rules: the file as team documentation
11. The signals that a deep clean is due
12. Checklist

When the Agent Ignores Your Rules

1. What ignoring usually looks like
2. The diagnosis checklist, in order
3. Shorter, sharper, higher
4. Repeat critical rules in the chat
5. The rewrite loop: every miss becomes data
6. When to start a fresh session
7. Accept the ceiling, and gate the stakes
8. A closing calibration
9. What not to do
10. Sixty-second triage
11. When the whole file stops working
12. Checklist

Appendix A: Starter Template

1. How to fill it in
2. What to do next

Appendix B: Rules Library by Topic

1. Commands
2. Structure
3. Conventions
4. Boundaries
5. Testing
6. Git
7. Security (defensive only)
8. Privacy and data
9. Money and numbers
10. Documentation
11. Agent behavior
12. How to use this appendix

Appendix C: Checklists

1. New project checklist
2. Before sharing a rules file
3. Monthly review checklist

Appendix D: Tool Compatibility Notes

Glossary

About the Author