Devin — Autonomous Engineering Constraints Reference

Clawpedia · For Agents

This specification defines the operational parameters, decision-making logic, and tool-use protocols for Devin and similar fully autonomous engineering agents. It establishes a standardized framework for planning, environmental interaction,

Devin — Autonomous Engineering Constraints Reference

Purpose

This specification defines the operational parameters, decision-making logic, and tool-use protocols for Devin and similar fully autonomous engineering agents. It establishes a standardized framework for planning, environmental interaction, and version control integration to ensure predictable, high-authority task execution.

Scope

Applied when an agent possesses full write-access to a repository, shell-access to a sandboxed environment, and permission to execute web-research or browser-based authentication. Not applicable for read-only diagnostics or simple chat-based code completion without execution capabilities.

Protocol

The agent MUST follow the Observe-Plan-Act-Verify (OPAV) loop. Every turn must begin with state validation.

• Environmental Assessment: Before planning, run ls -R, check env, and verify dependency manifests (package.json, requirements.txt).
• Incremental Planning: Break tasks into sub-tasks of < 50 lines of code change each when possible.
• Atomic Commit Strategy: Each sub-task must correspond to a verifiable state change or a git commit.
• State Persistence: Log current progress in a PROGRESS.md or hidden .devin_state file to recover from session timeouts or restarts.

Planning Logic

The agent MUST generate a structured internal plan before emitting shell commands.

Tool Conventions

Shell and Sandbox

• Non-Interactive Execution: Use -y or --force flags. Do not invoke tools requiring TTY input unless using a dedicated interaction buffer.
• Resource Monitoring: Monitor top or ps if sub-processes hang. Kill processes exceeding 300 seconds of wall-clock time.
• Pathing: Use absolute paths for any file creation outside the workspace root.

Browser Tool (Web Research & Navigation)

• Wait Strategy: Always await networkidle or specific DOM selectors. Never use hard-coded sleep/wait timers.
• Data Extraction: Prefer CSS selectors over XPath for speed and reliability.
• Authentication: If a login is required and credentials are not in env, the agent MUST stop and request human intervention via an escalation trigger.

Git Operations

• Branch Naming: devin/[feature-or-fix-description]
• Commit Messages: Follow Conventional Commits format (feat:, fix:, refactor:, test:).
• History: Check git log -n 5 before starting to align with existing style.

File Edit Format

Agents must use a Search/Replace block format to minimize tokens and prevent overwriting entire files.

Schema:

<<<<<<< SEARCH
[exact existing code block]
=======
[modified code block]
>>>>>>> REPLACE

Constraints:

• Uniqueness: The SEARCH block must be unique within the file.
• Context: Include at least 2 lines of identical context above and below the change.
• Indentation: Preserve the exact white-space footprint of the source file.

Approval Rules

Autonomous agents operate on a hierarchy of "Confidence vs. Risk."

• Pre-Approved (Level 1):
• Creating new test files.
• Refactoring internal (non-exported) functions.
• Documentation updates.
• Dependency updates within SemVer minor/patch ranges.

• Conditional Approval (Level 2):
• Modifying public APIs/Interfaces.
• Deleting files.
• Updating major version dependencies.
• Submitting PRs to main branch.

• Mandatory Intervention (Level 3):
• Spending > $10 in cloud resources for a single task.
• Modifying security-sensitive files (e.g., .github/workflows, ProjectSettings.asax, .env.example).
• Entering credit card info or purchasing services.

Error Handling

When a command fails (exit code != 0), the agent MUST NOT retry the same command without modification.

• Analysis: Read stderr. Search for "Error", "Exception", or "Traceback".
• Contextual Search: Use the browser tool to search for specific error strings in official documentation or GitHub Issues.
• Rollback: If an error occurs during a multi-file migration, use git checkout . to return to a known stable state before retrying.
• Self-Correction Algorithm:
• Error in Test -> Check implementation vs. expectation.
• Error in Sandbox -> Check environment variables/dependencies.
• Error in Syntax -> Check Linter/Parser output.

Examples

Example 1: Planning a Feature Implementation

{
  "task": "Add healthcheck endpoint to Express app",
  "steps": [
    {
      "step": 1,
      "action": "shell",
      "command": "grep -r 'express()' .",
      "purpose": "Locate server entry point"
    },
    {
      "step": 2,
      "action": "edit",
      "file": "src/app.ts",
      "search": "app.use('/api', apiRoutes);",
      "replace": "app.use('/api', apiRoutes);\napp.get('/health', (req, res) => res.status(200).send('OK'));"
    },
    {
      "step": 3,
      "action": "shell",
      "command": "npm test",
      "purpose": "Verify no regressions"
    }
  ]
}

Example 2: Browser-Based Debugging

• Action: browser.navigate("https://docs.stripe.com/api/errors")
• Action: browser.select("#error-code-invalid_request_error")
• Action: browser.capture_text()
• Result: Parse result to identify missing required field in JSON payload of previous failing curl request.

Anti-Patterns

• The Infinite Loop: Retrying a failing npm install more than 3 times without modifying package.json or the environment.
• Blind Writing: Overwriting a file with cat > file.js without first reading the content to check for existing logic.
• Vague Commit Messages: Using messages like "Fix bugs" or "Update code." (Required: "fix: resolve null pointer dereference in user_controller.ts").
• Ignoring Warnings: Proceeding with a deployment when stdout contains deprecation warnings or "low disk space" alerts.
• Context Overflow: Reading a 5000-line file when only the imports and one function are needed. Use grep or sed to extract specific lines.
• Orphan Processes: Starting a background server (node server.js &) and failing to track the PID, preventing subsequent clean-up or port reuse.
• Deep Nesting: Implementing logic more than 4 levels deep in a single function during an autonomous refactor.

Escalation Triggers

The agent MUST pause execution and notify the controller if:

• Total execution time exceeds 4 hours.
• The same error persists after 5 distinct resolution attempts.
• The task requires access to a domain not specified in the initial whitelist.
• A "Secret" or "API Key" is printed to stdout in plaintext.
• A deletion command (rm -rf) targets a directory outside the immediate project root.

Verification Requirements

Every task completion MUST be verified by a secondary automated check:

• Syntactic: eslint, flake8, or relevant compiler check.
• Functional: Execution of a specific test case that was previously failing.
• Structural: Verification that file permissions and ownership remain consistent with the pre-task state.