Devin AI System Prompt Architecture: Playbooks, Rules, and Subagent Profiles

The Hierarchical Prompt Architecture

Devin constructs its active context by layering four distinct operational tiers:

1. Base Runtime System Prompt: Authored and maintained by Cognition. Governs Devin's core agent loop, tool calling protocols, shell command parsing, sandboxed Ubuntu execution environment, browser interaction, and failure recovery cycles.

2. Persistent Repository Rules: Defined by engineering teams in AGENTS.md, AGENTS.local.md, or modular rule files under .devin/rules/. Enforces codebase conventions, linting commands, language preferences, and tool restrictions across all sessions in a repository.

3. Subagent Profiles: Defined under .devin/agents/. Establishes role-specific system prompts, allowed tools, and model routing for child agents spawned during complex parallel work.

4. Playbooks and Task Directives: Reusable procedural blueprints (.devin.md files or web app playbooks) and runtime user prompts. Dictates step-by-step procedures, acceptance criteria, and specific business logic for individual engineering jobs.

Runtime Context Assembly and Token Budgeting

Devin combines these layers at session initialization. The base prompt initializes the reasoning container, after which repository rules establish project constraints. When a user invokes a playbook or initiates a specific job, those instructions bind to the active conversation thread.

Cognition explicitly advises keeping rules and AGENTS.md files as compact as possible. When teams place hundreds of lines of documentation or style guides directly into persistent rules, the model experiences attention dilution. Long prompt contexts increase token consumption on every reasoning step and make it easier for an agent to miss critical constraints. Offloading detailed technical references to on-demand skills or targeted playbooks ensures the primary prompt stack remains focused on essential guardrails.

Rule Activation Modes and Frontmatter Triggers

Modular rule files stored in .devin/rules/*.md support YAML frontmatter to control when instructions enter context:

Here is an example of a glob-activated rule stored at .devin/rules/api-standards.md:

---
description: "API design and error response standards"
globs: "src/controllers/**/*.ts"
---

All API endpoints must return JSON responses matching the standard envelope:
- Success responses must wrap data in a `data` object.
- Error responses must return an `error` object containing `code`, `message`, and `details`.
- Never return raw database model instances directly to the client.

Structuring Effective Project Rules

Project rules should focus on operational guardrails rather than generic programming advice. Effective rules share several characteristics:

• Imperative Directives: State exact commands rather than suggestions. Use "Run pnpm test before committing" instead of "Make sure tests pass".
• Concrete File Paths: Point to reference files and configuration paths directly so the agent can inspect existing patterns.
• Negative Constraints: Explicitly state actions the agent should avoid, such as modifying lockfiles without approval or introducing new third-party dependencies.

Built-In and Custom Subagent Profiles

Devin provides two built-in profiles, alongside support for custom profiles defined in .devin/agents/:

• subagent_explore: Built-in profile for read-only codebase research. Uses the default subagent model, which resolves to SWE-1.6 by default. It is restricted to read-only tools: read, grep, glob, and web search. It cannot edit files or make arbitrary network requests.
• subagent_general: Built-in general-purpose profile. Inherits the parent agent's selected model, such as Claude Opus or GPT-5. Has access to the full toolset, including file modifications and shell execution.
• Custom Subagents: Defined in .devin/agents/<name>.md or .devin/agents/<name>/AGENT.md. Allows teams to specify custom system prompts, pin dedicated models, and restrict allowed tools.

Defining Custom Subagent Profiles

Custom subagents use YAML frontmatter followed by a markdown system prompt. Teams can pin a fast model and restrict tool access to prevent accidental regressions.

Here is a custom code review subagent defined at .devin/agents/reviewer.md:

---
name: reviewer
description: Reviews pull requests for security and test coverage
model: sonnet
allowed-tools:
  - read
  - grep
  - glob
  - exec
max-nesting: 1
---

You are a dedicated code review subagent. Your job is to inspect proposed changes before a pull request is finalized.

Review checklist:
1. Verify that all new endpoints have corresponding integration tests.
2. Check for SQL injection vulnerabilities and unescaped input parameters.
3. Confirm that no secrets or API keys exist in code or comments.
4. Run `npm test` using the exec tool and report all failures with file paths and line numbers.

Execution Modes and Cost Control

Subagents run in two operational modes:

• Foreground: Runs inline within the active session. The parent agent pauses while the subagent works. The user reviews and approves tool calls as they occur.
• Background: Runs concurrently in parallel. The parent agent continues working on other jobs. The subagent inherits pre-approved tool permissions; any unapproved tool is denied automatically.

Subagent compute costs scale with each worker spawned. By default, subagents cannot spawn child subagents. Setting the max-nesting field in custom profile frontmatter allows controlled multi-level delegation for large refactors while capping recursion depth to prevent runaway spend.

Core Structure of a Devin Playbook

Effective playbooks contain five structured components:

1. Overview: Brief explanation of the operational objective and scope.
2. What Is Needed From User: Explicit inputs required upfront, such as target endpoints, database names, or API credentials.
3. Procedure: Step-by-step imperative actions, written with one step per line. Steps should be mutually exclusive and collectively exhaustive.
4. Specifications: Concrete postconditions and verification criteria that must pass before Devin marks the task complete.
5. Advice and Forbidden Actions: Guidance that overrides default model tendencies, paired with hard guardrails preventing destructive commands.

Production Playbook Example: Database Schema Migration

Below is a complete playbook saved as database-migration.devin.md. Teams can trigger this playbook using a macro or attach it directly to a Devin session:

Playbook: Safe Database Schema Migration

## Overview
Execute an incremental schema migration for PostgreSQL services using Prisma.

## What Is Needed From User
- Name of the target migration
- Target database environment (development or staging)

## Procedure
1. Inspect the Prisma schema file at `prisma/schema.prisma` for uncommitted changes.
2. Generate a draft migration file using `npx prisma migrate dev --create-only --name <migration-name>`.
3. Inspect the generated SQL script in `prisma/migrations/` to verify table indices and column types.
4. Run existing database unit tests using `npm run test:db`.
5. Apply the migration to the local test database using `npx prisma migrate deploy`.
6. Execute the verification test suite to ensure existing queries remain functional.

## Specifications
-

The migration must complete with zero schema validation errors.
- All database unit tests in `test/database/` must pass.
- No existing tables or columns may be dropped without explicit user approval.

## Advice and Forbidden Actions
- Never run `prisma migrate reset` or any command that deletes existing database data.
- If a foreign key constraint fails during migration, halt execution and report the constraint conflict.

Playbook Macros and Enterprise Distribution

Teams can assign short macros starting with ! (such as !db-migrate or !security-check) to playbooks. Typing the macro into the Devin prompt input attaches the playbook instantly.

Playbooks maintain full version history within Devin, allowing teams to audit changes and revert modifications when workflows evolve. In enterprise organizations, administrators can publish playbooks globally across all workspaces to maintain consistent engineering practices across distributed teams.

Connecting Devin to Fast.io via the Model Context Protocol

Developers connect Devin to Fast.io workspaces using the remote Model Context Protocol (MCP) server. Teams configure Fast.io Agent Storage over Streamable HTTP at https://mcp.fast.io/mcp (or https://mcp.fast.io/mcp/key with Bearer authentication), alongside a legacy SSE transport at https://mcp.fast.io/sse. Complete server specifications are detailed in the Fast.io Agent Storage guide and the Model Context Protocol specification at https://mcp.fast.io/skill.md, alongside onboarding notes at https://fast.io/llms.txt.

Developers configure Fast.io in their Devin environment settings:

{
  "mcpServers": {
    "fastio": {
      "url": "https://mcp.fast.io/mcp/key",
      "headers": {
        "Authorization": "Bearer YOUR_FASTIO_API_KEY"
      }
    }
  }
}

Through this connection, Devin queries prompt templates, reads architecture specifications using hybrid search (combining exact full-text and semantic retrieval), and writes execution reports directly to persistent workspaces.

Structuring Prompt Assets in Fast.io Workspaces

An engineering organization can structure a dedicated Fast.io workspace to govern its agent configurations:

• /prompt-library/playbooks/: Houses standardized .devin.md workflows for migrations, releases, and refactoring.
• /prompt-library/agents/: Stores shared subagent profile definitions (reviewer.md, researcher.md).
• /architecture-specs/: Contains system design documents and API schemas, automatically indexed for semantic search once Intelligence is enabled.
• /execution-logs/: Receives build summaries, test outputs, and audit reports written by Devin sessions.

Every file in a Fast.io workspace maintains per-file version history, so developers can inspect edits and roll back prompt changes without Git merge conflicts. Fast.io Notes provide real-time co-editing where developers and agents collaborate on playbooks with live multiplayer cursors.

When Devin generates test reports or deployment summaries, teams can use Metadata Views to extract structured data automatically. Developers describe desired fields in plain English, and the system populates a typed data grid with fields such as test status, execution duration, and error codes.

Every organization starts with a 14-day free trial, which requires a credit card. Teams can review subscription tiers on the Fast.io pricing page: