Copy page

Microservices

Code Guardrails & File Operation Rules

Code Guardrails & File Operation Rules

Relevant source files

The following files were used as context for generating this wiki page:

• .devin/rules/code-guardrails.md
• .devin/rules/file-operations.md
• .devin/rules/temp-files.md

This page documents the technical constraints and operational protocols governing AI agent behavior within the primebrick-v3-microservices repository. These rules ensure system stability, maintain architectural integrity, and prevent repository pollution through strict execution limits and file management policies.

1. Code Execution Guardrails

The repository enforces a "fail-fast" policy for all automated code modifications. These guardrails prevent the AI agent from entering recursive error-correction loops or introducing large-scale regressions.

1.1 Self-Correction & Retry Logic

AI agents are permitted a maximum of 2 self-correction attempts to resolve terminal command failures, linter errors, or test regressions .devin/rules/code-guardrails.md:6-7. If the error persists after the second attempt, the agent must immediately halt all operations .devin/rules/code-guardrails.md:8.

1.2 BLOCKED State & Escalation

Upon reaching the retry limit, the system transitions to a BLOCKED state .devin/rules/code-guardrails.md:9. The agent is required to:

1. Update the Kanban board/Command Center status to BLOCKED.
2. Report the full error logs in the communication channel.
3. Wait for manual user intervention before proceeding .devin/rules/code-guardrails.md:10.

1.3 Scope Locking & Atomicity

To maintain architectural consistency, agents operate under "Scope Locking" constraints:

• Signature Protection: Existing function signatures, API endpoints, and shared state structures cannot be modified unless specifically authorized in a pre-approved Markdown plan .devin/rules/code-guardrails.md:13.
• Iterative Application: Changes must be atomic. Agents must run linters or tests after modifying single modules rather than batching edits across multiple files .devin/rules/code-guardrails.md:14.

Sources: .devin/rules/code-guardrails.md:1-15

---

2. File Operation Rules

File operations prioritize empirical verification over IDE state. This prevents errors caused by out-of-sync editor buffers or memory-resident file copies.

2.1 Empirical Verification Workflow

Agents must never assume a file's state based on the editor's context .devin/rules/file-operations.md:20-22. Every operation follows a strict verification cycle using system-level tools.

File Verification Process Flow

Code
graph TD
    "START"["Start File Operation"] --> "VERIFY_EXIST"["Verify Existence via Test-Path/ls"]
    "VERIFY_EXIST" --> "VERIFY_CONTENT"["Verify Content via read/grep"]
    "VERIFY_CONTENT" --> "EXECUTE"["Execute File Operation"]
    "EXECUTE" --> "POST_VERIFY"["Post-Operation Empirical Check"]
    "POST_VERIFY" --> "END"["Operation Complete"]

Sources: .devin/rules/file-operations.md:15-31

2.2 Tool-Based Verification

The following tools are mandated for file state confirmation:

• Existence: Test-Path (PowerShell) or ls (Unix) .devin/rules/file-operations.md:16.
• Content: read tool .devin/rules/file-operations.md:17.
• Search: grep tool for pattern matching .devin/rules/file-operations.md:18.
• Discovery: find_file_by_name for location mapping .devin/rules/file-operations.md:19.

2.3 Path Conventions

• Relative Paths: Agents must use relative paths from the workspace root (e.g., primebrick-fe-v3/src/...) .devin/rules/file-operations.md:34.
• Pathing Restrictions: Absolute paths and leading slashes are prohibited unless explicitly required by a specific tool .devin/rules/file-operations.md:35-36.

Sources: .devin/rules/file-operations.md:1-42

---

3. Temporary File Management

To maintain a clean repository state, the creation of temporary files (scripts, patches, or intermediate logs) within the project directories is strictly forbidden .devin/rules/temp-files.md:11-15.

3.1 Designated Temp Locations

If temporary files are necessary, they must be stored in external system directories:

• Windows: d:\git\primebrick\temp\ .devin/rules/temp-files.md:18.
• Linux/Mac: /tmp/ or /var/tmp/ .devin/rules/temp-files.md:19.

3.2 Cleanup Policy

All temporary files must be removed immediately after use using Remove-Item -Force or rm -f .devin/rules/temp-files.md:22. Cleanup must be empirically verified with Test-Path before the agent concludes the session .devin/rules/temp-files.md:24,35.

3.3 In-Memory Preference

Agents are instructed to prefer in-memory operations over disk writes whenever possible, utilizing string manipulation or subagents for complex tasks .devin/rules/temp-files.md:26-30.

Temp File Life Cycle

Code
sequenceDiagram
    participant "Agent" as Agent Logic
    participant "Temp" as d:\git\primebrick\temp\
    participant "Repo" as primebrick-us-v3/

    "Agent"->>"Temp": Create temporary script/patch
    Note over "Agent", "Repo": Prohibited: Writing temp to Repo/
    "Agent"->>"Agent": Execute logic using Temp file
    "Agent"->>"Temp": Remove-Item -Force
    "Agent"->>"Temp": Test-Path (Verify deletion)

Sources: .devin/rules/temp-files.md:1-37

---

4. Summary of Constraints

Category	Rule	Enforcement Mechanism
Execution	Max 2 Retries	Hard stop and transition to BLOCKED state .devin/rules/code-guardrails.md:7-9
Modification	Scope Locking	Prohibition of unauthorized signature changes .devin/rules/code-guardrails.md:13
Verification	Empirical Tools	Mandatory use of ls, grep, and read over IDE context .devin/rules/file-operations.md:15-20
Pollution	Temp Isolation	No .js, .py, or .patch files in project repos .devin/rules/temp-files.md:11-15
IDE Interaction	No Auto-Open	Plans and internal scripts must not be opened in the editor .devin/rules/file-operations.md:11-13

Sources: .devin/rules/code-guardrails.md:1-15, .devin/rules/file-operations.md:1-42, .devin/rules/temp-files.md:1-37

---