|
| 1 | +--- |
| 2 | +title: "Working with AI Agents" |
| 3 | +linkTitle: "AI Agents" |
| 4 | +weight: 30 |
| 5 | +description: "How to get AI coding agents to follow DevRail standards in your projects." |
| 6 | +--- |
| 7 | + |
| 8 | +DevRail is designed so that AI coding agents (Claude Code, Cursor, OpenCode, Copilot, etc.) follow the same standards as human developers and CI pipelines. This page explains how to set it up and what to expect. |
| 9 | + |
| 10 | +## The Short Version |
| 11 | + |
| 12 | +If your project already has DevRail files (Makefile, `.devrail.yml`, DEVELOPMENT.md), just tell your agent: |
| 13 | + |
| 14 | +> This project follows DevRail development standards. Read DEVELOPMENT.md before making changes. Run `make check` before marking any task complete. |
| 15 | +
|
| 16 | +That's it. The agent instruction files (CLAUDE.md, AGENTS.md, etc.) already contain this directive, so agents that read them will follow DevRail automatically. |
| 17 | + |
| 18 | +## How It Works |
| 19 | + |
| 20 | +DevRail communicates standards to agents through a **hybrid shim** pattern: |
| 21 | + |
| 22 | +``` |
| 23 | +CLAUDE.md / AGENTS.md / .cursorrules / .opencode/agents.yaml |
| 24 | + │ |
| 25 | + ├── Points to DEVELOPMENT.md (full standards reference) |
| 26 | + │ |
| 27 | + └── Inlines 6 critical rules (minimum viable compliance) |
| 28 | +``` |
| 29 | + |
| 30 | +**Agents that follow cross-file references** (like Claude Code) will read DEVELOPMENT.md and get the complete picture -- language-specific tooling, Makefile contract, shell conventions, everything. |
| 31 | + |
| 32 | +**Agents that ignore cross-file references** still get the six critical rules inlined directly in their instruction file. This ensures minimum compliance regardless of agent capability. |
| 33 | + |
| 34 | +## Setting Up a Project for Agent Use |
| 35 | + |
| 36 | +### Option A: Start from a Template |
| 37 | + |
| 38 | +If you create a project from a [DevRail template](/docs/getting-started/new-project/), all agent instruction files are already included. No additional setup needed. |
| 39 | + |
| 40 | +### Option B: Retrofit an Existing Project |
| 41 | + |
| 42 | +If you have an existing project, follow the [Retrofit Guide](/docs/getting-started/retrofit/) to add DevRail files. The agent instruction files are listed as optional, but **they are required if you want agents to follow DevRail standards**. |
| 43 | + |
| 44 | +Copy all four shim files: |
| 45 | + |
| 46 | +```bash |
| 47 | +curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/CLAUDE.md |
| 48 | +curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/AGENTS.md |
| 49 | +curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/.cursorrules |
| 50 | +mkdir -p .opencode |
| 51 | +curl -o .opencode/agents.yaml https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/.opencode/agents.yaml |
| 52 | +``` |
| 53 | + |
| 54 | +### Option C: Point an Agent at DevRail Without Files |
| 55 | + |
| 56 | +If you do not want to commit DevRail files yet, you can paste instructions directly into your agent's context. Here is a prompt you can use: |
| 57 | + |
| 58 | +> You are working on a project that follows DevRail development standards (https://devrail.dev). |
| 59 | +> |
| 60 | +> **Key rules:** |
| 61 | +> 1. Run `make check` before completing any task. This runs all linters, formatters, security scanners, and tests inside a Docker container. |
| 62 | +> 2. Use conventional commits: `type(scope): description`. |
| 63 | +> 3. Never install tools on the host. All tools run inside the `ghcr.io/devrail-dev/dev-toolchain:v1` container via `make` targets. |
| 64 | +> 4. Respect `.editorconfig` formatting rules. |
| 65 | +> |
| 66 | +> **Available `make` targets:** |
| 67 | +> - `make lint` -- run linters |
| 68 | +> - `make format` -- check formatting |
| 69 | +> - `make test` -- run tests |
| 70 | +> - `make security` -- run security scanners |
| 71 | +> - `make check` -- run everything |
| 72 | +> |
| 73 | +> Languages are declared in `.devrail.yml`. The Makefile reads this file to determine which tools to run. See https://devrail.dev/docs/standards/ for per-language tool details. |
| 74 | +
|
| 75 | +## Example Prompts |
| 76 | + |
| 77 | +### Retrofitting an existing project |
| 78 | + |
| 79 | +> I want to adopt DevRail standards in this project. Read https://devrail.dev/docs/getting-started/retrofit/ and follow the steps. This is a Ruby on Rails project, so set `languages: [ruby]` in `.devrail.yml`. After adding the DevRail files, run `make check` and fix any findings. |
| 80 | +
|
| 81 | +### Ongoing development |
| 82 | + |
| 83 | +> Before you finish, run `make check` and fix any failures. Use conventional commit messages. |
| 84 | +
|
| 85 | +### Explaining what DevRail does |
| 86 | + |
| 87 | +> Read https://devrail.dev/docs/standards/ and tell me which tools will run for my project based on the languages in `.devrail.yml`. |
| 88 | +
|
| 89 | +## What Agents See |
| 90 | + |
| 91 | +When an agent reads the project's CLAUDE.md (or equivalent), it learns: |
| 92 | + |
| 93 | +1. **DEVELOPMENT.md is the canonical reference.** It contains the full Makefile contract, per-language tooling, shell conventions, and logging standards. |
| 94 | +2. **Six critical rules must always be followed.** These are inlined so the agent cannot miss them. |
| 95 | +3. **`make check` is the single gate.** No task is complete until it passes. |
| 96 | +4. **Everything runs in Docker.** The agent should never try to install tools on the host. |
| 97 | + |
| 98 | +## Verifying Agent Compliance |
| 99 | + |
| 100 | +After an agent completes a task, check that it followed DevRail: |
| 101 | + |
| 102 | +| Check | What to look for | |
| 103 | +|---|---| |
| 104 | +| Commit messages | Follow `type(scope): description` format | |
| 105 | +| `make check` | Agent ran it and it passes | |
| 106 | +| No host tool installs | Agent did not run `pip install`, `gem install`, `npm install -g`, etc. for linting/formatting tools | |
| 107 | +| `.editorconfig` respected | Indentation, line endings, and trailing whitespace match project rules | |
| 108 | + |
| 109 | +If an agent consistently ignores standards, add the critical rules directly to its system prompt or context window rather than relying on file references. |
| 110 | + |
| 111 | +## Which File Does My Agent Read? |
| 112 | + |
| 113 | +| Agent | Instruction File | |
| 114 | +|---|---| |
| 115 | +| Claude Code | `CLAUDE.md` | |
| 116 | +| Cursor | `.cursorrules` | |
| 117 | +| OpenCode | `.opencode/agents.yaml` | |
| 118 | +| Other / generic | `AGENTS.md` | |
| 119 | + |
| 120 | +All four files contain identical content in different formats. You only need the file(s) for the agent(s) you use, but shipping all four costs nothing and covers future tool changes. |
0 commit comments