AGENTS.md

Table of contents

What is it?

It is a standardized, open-source documentation file designed to serve as the “README for agents”. It provides a dedicated and predictable location where coding AI agents (such as GitHub Copilot, Cursor, or Claude Code) can find the context, commands, and conventions necessary to work effectively on a software project. Its goal is to unify instructions for AI into a single file that works across any development environment.

How to use AGENTS.md?

To integrate this standard into your workflow, follow these steps:

1. Add AGENTS.md: Create a new file named AGENTS.md in the root directory of your project.

2. Define the Rules: Populate the file with the key information the agent needs. Although the format is flexible, you should typically include:

   • Project Overview: A brief explanation of the architecture and directory structure.
   • Setup Commands: Precise instructions for installing dependencies and setting up the environment.
   • Testing Instructions: The exact commands to run tests and validate changes.
   • Code Style: Linting rules, formatting, and preferred design patterns.
   • Git/PR Instructions: Required format for commit messages and requirements before merging code.

3. Automatic Detection: AI coding assistants scanning your repository will automatically read this file to understand the project context.

4. Iterate: Start simple with bullet points. As you notice the AI making mistakes (e.g., using an old library version), add a rule to AGENTS.md to fix it permanently.

Pro Tips for Optimization

• ”Dos and Don’ts” Lists: Be extremely explicit about libraries and versions to prevent the AI from guessing.
  • Example: “DO use SwiftUI for new views. DON’T use Storyboards or UIKit.”
• Targeted Commands: Save time by telling the AI how to check a single file instead of running the whole suite.
  • Example: “To check a specific file: swiftlint lint --path <filepath>.”
• Good vs. Bad Examples: If your codebase has legacy code (old patterns), explicitly point the AI to the “Gold Standard” files.
  • Example: “See Features/Home/HomeView.swift for the correct MVVM pattern. Avoid patterns found in Legacy/OldViewController.m.”
• Project Shortcuts: Don’t make the AI “explore” every time. Tell it where key things are.
  • Example: “Navigation logic is handled in Coordinators/AppCoordinator.swift.”

AGENTS.md Example

# AGENTS.md

## Project Context

- This is a native iOS app using SwiftUI and Combine.
- The architecture follows the MVVM-C (Model-View-ViewModel-Coordinator) pattern.
- Networking is handled by `Alamofire`.

## Non-Negotiable Rules (Dos & Don'ts)

- **DO** use `struct` for Views and Models.
- **DO** use `final class` for ViewModels and Services.
- **DON'T** use Storyboards (.storyboard) or XIBs; use programmatic UI or SwiftUI.
- **DON'T** force unwrap optionals (`!`); use `if let` or `guard let`.

## Optimization & Commands

- **Install dependencies:** `pod install` (CocoaPods)
- **Run Tests:** `xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'`
- **Lint Specific File:** `swiftlint lint --path <file_path>`
- **Build:** `xcodebuild -scheme MyApp build`

## Reference Examples

- **Good Component:** See `Sources/UI/Components/PrimaryButton.swift` for proper accessibility and theming.
- **Bad Component:** Ignore `Sources/Legacy/Objective-C/OldTableViewController.m`.