A new teammate gets an onboarding guide. An agent needs the same, written in a form it can read at the start of every task.
What to include
- How to build, test, and lint the project, with exact commands.
- The architecture and where different kinds of code live.
- Style and naming conventions.
- Explicit prohibitions, such as not editing generated files or project settings.
- How to ask for clarification or stop when unsure.
Write specific rules
"Write clean code" is not actionable. "View models are @Observable classes and do not import UIKit" is. Include short examples of the preferred patterns.
Keep it brief
Every token of instruction competes with the code the agent needs to read. Keep the file focused, and link to deeper documents only when needed.
Use decision records
Short architecture decision records explain why you chose one approach over another. They prevent an agent from "improving" your design in a direction you deliberately rejected.
Pair instructions with checks
Where a rule matters, back it with automated enforcement, such as a lint rule or build check. The agent sees the failure and corrects itself.
Keep it current
Review the instructions whenever conventions change. Outdated rules produce confident but wrong code.
Takeaway
Good repository instructions turn an agent from a generic coder into one that follows your team's practices.
Continue with the book
Explore the full treatment, worked examples, and exercises in Agentic iOS App Development.
Adapted from Agentic iOS App Development, published by Choral Software. Article text and original examples © 2026 Choral Software. All rights reserved.