Agentic workflow: the founding principles

After Cursor IDE, after GitHub Copilot, after a first wave of tools that “suggested code”, we’ve entered something different. Coding agents no longer suggest — they execute, read files, run tests, commit code. The change isn’t one of degree, it’s one of kind.

This guide documents the principles that make an agentic workflow actually work in production — not the YouTube demos, not the synthetic benchmarks. What works on an 80k-line Symfony project day to day.

What actually changes with agents?

The most common mistake is treating an AI agent as an enhanced autocomplete engine. You ask for a function, it generates one, you copy-paste.

What changes with agents is the granularity of delegation. You no longer delegate a line or a block — you delegate an intent with a defined scope:

“Refactor the OrderRepository service to extract the discount calculation logic into a dedicated DiscountCalculator. Existing tests must pass. Create missing tests for edge cases identified in TODO comments.”

The agent reads the files, understands the context, writes the code, runs the tests, fixes errors, and presents the result. In a 20-minute session, you get what used to take 2 hours — with tests.

The gain isn’t “the AI writes code for me”. The gain is the shift in abstraction level at which you work.

How do you break down a task for an agent?

Decomposition is the core skill of an agentic workflow. A poorly briefed agent produces code that compiles but doesn’t do what you wanted. A well briefed agent produces exactly what you asked — which often reveals that what you asked wasn’t what you wanted.

Principle 1: one session = one verifiable deliverable

Each session should end with something you can objectively validate: tests pass, the PR is readable, the bug is reproduced then fixed. If you can’t define the exit condition, the task is too big.

❌ "Improve the payment service"
✅ "Add handling for the case where payment is rejected by the Stripe API (code 402)
    with automatic retry x 2, error logging, and admin notification.
    Unit tests must cover all 3 cases: success, rejection, timeout."

Principle 2: minimum viable context

Loading the entire codebase into context is counterproductive. The bigger the context, the faster the context rot . Best practice is to only load files directly related to the task, and use persistent context files (CLAUDE.md, AGENTS.md) for structural project information.

# OpenCode — load only the relevant files
> /add src/Service/OrderService.php src/Repository/OrderRepository.php
> /add tests/Service/OrderServiceTest.php

Principle 3: constraint instructions

Telling the agent what it must not do is as important as telling it what to do. Without constraints, the agent optimizes for “something that looks like a solution” rather than “something that respects the project’s conventions”.

"Don't modify the service's public interface.
 Use the existing assertion helpers in AbstractServiceTest.
 Follow the naming convention: unit tests end in Test.php."

How do you manage context over time?

The context window of an LLM is a finite resource that degrades. As a session grows longer, the initial instructions lose their influence on the agent’s decisions. That’s context rot — and it’s the #1 problem of agentic workflows in production.

Cut sessions at the right time

The rule of thumb: cut a session after 3-4 modified files or when the initial task is complete. No “catch-all” sessions that chain topics together.

Persistent context files

A CLAUDE.md or AGENTS.md file at the project root is automatically read by most agents. It should contain what the agent needs to know about the project to work correctly, not the project’s history:

# Project conventions

- PHP 8.3 + Symfony 7.1 + API Platform 3.x
- Tests: PHPUnit 11, namespacing App\Tests\[Domain]
- Repositories inherit from AbstractRepository, not directly from Doctrine
- Test environment: DATABASE_URL_TEST in .env.test.local
- For migrations: `php bin/console doctrine:migrations:diff` then manual review

This file is the agent’s permanent memory for your project. It compensates for the fact that the LLM has no memory between sessions.

Multi-session with handoff

For long tasks, structure them as sessions with explicit checkpoints:

Session 1: "Analyze service X and produce a refactoring plan in REFACTOR_PLAN.md"
Session 2: "Implement steps 1 and 2 from the plan in REFACTOR_PLAN.md"
Session 3: "Implement steps 3 and 4, verify all tests pass"

The plan file is both the deliverable of one session and the context for the next.

What are the anti-patterns to avoid?

The agent as oracle

Asking the agent “what’s the best architecture for X” and applying its answer without thinking. The agent optimizes for response coherence, not for your business context. It’s good at implementing decisions, not at making them for you.

The yolo commit

Merging the agent’s code directly without review. Even with the best prompts, the agent can introduce subtle bugs, broken conventions, or premature optimizations. Human review is not optional — it’s where the real engineering happens.

The infinite context

Passing the entire codebase as context “so the agent understands better”. In practice, it dilutes instructions and accelerates context rot. Focused context = better results.

Ambiguous instructions

“Improve performance” or “clean up the code”. Without a defined success criterion, the agent invents its own — which generally doesn’t match yours.

What does this concretely change in a workflow?

After several months of daily use on a Symfony/TypeScript production project, here are the lasting changes:

Task granularity has decreased. We break things down more finely, reducing the risk of each change and speeding up reviews. 500-line PRs became 50-100 line PRs with a clear scope.

Time spent on “plumbing” has dropped. Boilerplate tests, schema migrations, API documentation, adding validation — everything mechanical and predictable gets delegated. Attention focuses on business logic and architecture decisions.

Documentation is better. When you brief the agent, you’re forced to articulate precisely what you want. Those briefs often become the basis for task documentation.

The feedback loop is shorter. With an agent running tests in real time, you know if something is broken in 2 minutes rather than 20. This encourages small, verifiable commits.

Resources & references

• OpenCode — terminal-first agent, MIT, multi-provider
• Anthropic: building effective agents — reference on production agent patterns
• Model Context Protocol — standard for extending agents via tool servers
• Guide: Managing context in multi-agent workflows
• Guide: Prompt engineering for coding agents