Coding Agent Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Coding Agent system is designed to automate software development tasks within the Recoup monorepo using AI agents like Claude Code. These agents operate within isolated Vercel Sandbox environments to perform code modifications, synchronize submodules, and manage the Git workflow from branch creation to Pull Request (PR) submission.
The guidelines ensure that agents follow a structured, test-driven development (TDD) process and adhere to strict architectural principles such as the Single Responsibility Principle (SRP) and DRY (Don't Repeat Yourself). This system integrates with Trigger.dev v4 for background task processing and relies on specialized sandbox utilities for secure execution and state persistence via snapshots.
Sources: AGENTS.md, src/tasks/codingAgentTask.ts:16-25
Core Development Principles
Coding agents must adhere to the following technical and architectural standards:
- Test-Driven Development (TDD): Agents must follow the Red-Green-Refactor cycle. For bug fixes, a failing test must be written based on exact error messages before applying the fix.
- Architectural Cleanliness: Every exported function must follow SRP (one per file). Shared logic should be extracted into reusable utilities.
- Validation and Logging: All task inputs must be validated using Zod schemas. Agents must use the
@trigger.dev/sdk/v3logger for all execution details. - Git Integrity: Agents are prohibited from pushing directly to the
mainbranch. All changes must be pushed to feature branches and submitted via PRs.
Agent Execution Workflow
The lifecycle of a coding agent task involves setting up an isolated environment, preparing the source code, executing the AI agent, and processing the results.
Orchestration Flow
The following diagram illustrates the sequence of steps taken by the codingAgentTask to process a development prompt.
The workflow ensures that submodules are synced to the latest base branches (main or test) before the agent makes changes to prevent merge conflicts.
Sources: src/tasks/codingAgentTask.ts:31-77, src/sandboxes/git/syncMonorepoSubmodules.ts:21-41
Functional Components
| Component | Responsibility | Relevant Files |
|---|---|---|
| Sandbox | Provides an isolated Linux microVM for code execution. | src/sandboxes/getOrCreateSandbox.ts |
| Claude Agent | Executes claude -p with dangerously-skip-permissions to apply changes. | src/sandboxes/runClaudeCodeAgent.ts |
| Git Sync | Fetches and resets submodules to latest remote base branches. | src/sandboxes/git/syncMonorepoSubmodules.ts |
| PR Manager | Instructs the agent to commit, push, and use gh pr create. | src/sandboxes/pushAndCreatePRsViaAgent.ts |
Git Workflow Guidelines
Agents are required to follow a specific branch and commit strategy.
Submodule and Root Management
Changes are handled in two steps:
- Mono Repo Root: Changes to files like
progress.mdare committed and pushed directly tomain. - Submodules: Changes require a new branch (prefixed with
agent/), a commit with an automated message, and a PR created via the GitHub CLI (gh).
# Branch Naming Convention
agent/<prompt-slug>-<timestamp>
# PR Creation Command Instruction
gh pr create --repo <repo> --base <baseBranch> --head <branch> --title "agent: <prompt>" --body "Automated PR from coding agent."
Sources: src/sandboxes/pushAndCreatePRsViaAgent.ts:47-81, src/tasks/codingAgentTask.ts:54-56
PR Update Cycle
When human feedback is provided, the updatePRTask resumes the environment from a previous snapshot to apply revisions.
Sources: src/tasks/updatePRTask.ts:38-75
Build and Environment Configuration
Required Commands
Agents use pnpm for dependency management and deployment.
| Command | Purpose |
|---|---|
pnpm install | Install project dependencies |
pnpm dev | Start Trigger.dev development mode |
pnpm test | Run vitest suite |
pnpm run deploy:trigger-prod | Deploy workers to production |
Environment Variables
The agent environment requires specific tokens for operation:
CLAUDE_CODE_OAUTH_TOKEN: For agent authentication.GITHUB_TOKEN: For repository access and PR creation.CODING_AGENT_CALLBACK_URL: To notify the system of task completion.
Sources: src/sandboxes/runClaudeCodeAgent.ts:25-30, src/tasks/updatePRTask.ts:70-75
Conclusion
The Coding Agent Guidelines provide a robust framework for automated development. By leveraging isolated sandboxes, strict Git protocols, and TDD principles, the system ensures that AI-generated contributions remain high-quality and consistent with the project's monorepo architecture. The use of snapshots and background tasks allows for an iterative feedback loop between human developers and AI agents.