Devin CLI Implementation

Devin CLI Token Optimization

Layer 1 — Platform Mechanics

Devin’s own documentation is explicit here: prefer Skills over Rules/AGENTS.md wherever possible, because Skills load only when relevant while Rules and AGENTS.md load into every session regardless. Keep AGENTS.md deliberately small and use it mainly to point at which Skill applies to which scenario. Rules below the project root are lazily discovered — only pulled into context when the agent actually touches files in that directory — so scope project-specific detail to the narrowest directory that needs it.

Key Strategies:

• Skills Over Rules: Prefer Skills (load on-demand) over Rules/AGENTS.md (always load)
  • Skills load only when relevant to task
  • Rules/AGENTS.md load into every session
  • Keep AGENTS.md deliberately small
• Lazy-Loading Mechanics: Rules below project root are lazily discovered
  • Only loaded when agent touches files in that directory
  • Scope project-specific detail to narrowest directory
  • Reduces unnecessary context loading
• Pointer Pattern: Use AGENTS.md to point at Skills
  • “Use Skill X for scenario Y”
  • Keep actual instructions in Skills
  • Minimize always-loaded content

Layer 2 — Agent Operation

Turn recurring multi-step workflows into Playbooks (.devin.md files with Procedure / Specifications / Advice / success criteria / guardrails) instead of re-explaining the same task in prose every time. This is Devin’s core use case for general software engineering, not just documentation — dependency upgrades, ticket-to-PR, database migrations, and repeated scaffolding all fit the same pattern; a docs-build check is one narrow instance of it, not the norm. Devin CLI’s built-in duplicate-prompt detection (hashes your last 50 prompts) catches accidental re-runs before they burn ACUs twice. Use --json plus a dedicated --profile service for CI-style automation.

Operational Best Practices:

• Playbook Workflows: Convert recurring workflows to Playbooks
  • .devin.md files with structured format
  • Procedure / Specifications / Advice / success criteria / guardrails
  • Applicable to general software engineering, not just docs
  • Examples: dependency upgrades, ticket-to-PR, database migrations
• Duplicate-Prompt Detection: Built-in protection against re-runs
  • Hashes last 50 prompts
  • Catches accidental re-runs before they burn ACUs
  • Automatic cost control
• CI/Scripted Operations: Use --json + --profile service
  • Dedicated service profile for automation
  • JSON output for programmatic consumption
  • Optimized for non-interactive workflows

Layer 3 — Codebase Architecture

Deliver the Conventions content via AGENTS.md (auto-read), or promote it into Devin’s cloud-side Knowledge if you want it to persist without being re-read from a file each session.

Architecture Rules:

• AGENTS.md Delivery: Use AGENTS.md for architecture rules
  • Auto-read by Devin CLI
  • Shared with other tools
  • Keep consistent across codebase
• Cloud-Side Knowledge: Alternative for persistent rules
  • Promote to Devin’s cloud-side Knowledge
  • Persists without file re-reading
  • Useful for org-wide standards

Devin CLI-Specific Features

Playbooks

Devin’s Playbook system (.devin.md files) provides structured workflow automation:

• Structured Format: Procedure / Specifications / Advice / success criteria / guardrails
• General Applicability: Not just documentation — applies to all software engineering workflows
• Cost Optimization: Avoid re-explaining same task in prose repeatedly
• Workflow Types: Dependency upgrades, ticket-to-PR, database migrations, scaffolding

Practical Playbook Example

dependency-upgrade.devin.md - Dependency Upgrade Playbook

---
name: "Dependency Upgrade"
description: "Identify outdated dependencies, upgrade them incrementally by risk group, and open one PR per group with passing tests."
---

## Procedure

1. Read the current dependency manifest (`package.json` / `requirements.txt`
   / `go.mod` / equivalent) to establish a baseline.
2. Identify outdated packages using the ecosystem's standard tool
   (`npm outdated`, `pip list --outdated`, `go list -u -m all`).
3. Group upgrades by risk: patch/minor versions together, each major
   version bump on its own.
4. Upgrade one group at a time — never all packages in a single commit.
5. Run the full test suite after each group; stop and report if any group
   introduces a failure rather than continuing to the next group.
6. Open one PR per package group, including a changelog/diff summary for
   anything bumped a major version.

## Specifications

- Package manager: [npm / pip / go modules / etc.]
- Test command: [test command]
- Do not upgrade [pinned/frozen packages — e.g. a security-patched fork]
  without explicit instruction.

## Advice

- A major-version bump with no resulting test failure is not
  automatically safe — check the package's changelog for breaking
  changes your test suite might not cover (removed CLI flags, changed
  defaults, dropped platform support).
- If a lockfile conflict appears, resolve it by re-running install, not
  by hand-editing the lockfile.
- Treat transitive dependency bumps (pulled in by a direct upgrade) as
  part of the same risk group, not a separate one.

## Success criteria

- Each PR upgrades exactly one risk group.
- Full test suite passes after each group's upgrade.
- No files outside the manifest, lockfile, and code needed for
  compatibility are changed.

## Guardrails

- Never upgrade a dependency pinned for a documented reason — check
  comments and CHANGELOG entries first.
- Open the PR and stop; do not merge. A human approves and merges.
- Stop and escalate if more than [N] packages in a group fail at once —
  don't attempt to fix unrelated failures to force a group through.

Key Pattern: The Playbook captures the entire workflow structure once, eliminating the need to re-explain the same process in prose every time. This is Devin’s core strength for recurring software engineering tasks.

Lazy-Loading Rules

Devin’s lazy-loading mechanism for rules below project root:

• On-Demand Loading: Rules only load when agent touches files in that directory
• Directory Scoping: Scope project-specific detail to narrowest directory
• Cost Reduction: Reduces always-loaded token overhead
• Context Precision: Only relevant rules enter context

Skills System

Devin’s own documentation explicitly prefers Skills over Rules:

• Load-On-Demand: Skills only load when relevant
• Reduced Overhead: Unlike Rules, Skills don’t load into every session
• Task-Specific: Ideal for domain knowledge and procedures
• Organization: Better organization of capabilities

Duplicate-Prompt Detection

Built-in protection against wasteful re-runs:

• Hash-Based Detection: Hashes last 50 prompts
• Automatic Prevention: Catches accidental re-runs
• Cost Control: Prevents burning ACUs on duplicate work
• Transparent: Operates automatically without user intervention

Profile System

Devin’s profile system supports different operational modes:

• Service Profile: Dedicated profile for CI/automation
• Interactive Profile: Full capabilities for daily development
• JSON Output: --json flag for programmatic consumption
• Cost Optimization: Different profiles for different cost constraints