Most agentic coding setups fail the same way: not with a dramatic error, but with a slow collapse into “we’ll just prompt it manually.” The tooling looked promising in the demo. Somewhere between the first PR and the second sprint, the team stopped trusting it.
Building a reliable agentic coding workflow setup isn’t about picking the right tool — Claude Code, Cursor, and GitHub Actions each solve a distinct problem. The challenge is wiring them together so each agent knows exactly what it’s responsible for, when to act, and what to do when something goes wrong.
This guide walks you through the complete setup: CLAUDE.md authoring, lifecycle hooks, Cursor-to-Claude handoffs, and a production-ready GitHub Actions workflow. Everything here is copy-paste ready, opinionated, and built to survive beyond day one.
Why Most Agentic Coding Workflow Setups Break Down First
The numbers paint a clear picture of where the industry is headed. According to the JetBrains State of Developer Ecosystem 2025, 85% of developers report regular AI tool usage, and 62% rely on at least one coding assistant or agent. By late 2025, 90% of engineering teams reported AI in their workflows — up from 61% the year before.
But adoption doesn’t equal reliability. The Stack Overflow 2025 Developer Survey found that 87% of respondents are concerned about AI agent accuracy, and 81% have concerns about security and privacy. Independent analysis has shown AI-assisted code can increase issue counts approximately 1.7× without governance and review processes in place.
The failure mode isn’t the AI — it’s the absence of structure around it. Teams install the tools, give Claude a vague prompt, and call it an agentic pipeline. Three things kill these setups in the first sprint:
- A blank or bloated CLAUDE.md that leaves the agent guessing about architecture, conventions, and constraints
- No deterministic guardrails — everything depends on Claude making the right call, every time
- Tool confusion — using Cursor when you need Claude Code, or vice versa, because no one defined the split
The solution isn’t more tooling. It’s structure.
The Three Tools, One Pipeline: How Claude Code, Cursor, and GitHub Actions Each Fit
Think of your pipeline as three layers with distinct responsibilities.
Cursor handles IDE-native daily work: inline completions, quick refactors, tab-triggered suggestions, and the conversational back-and-forth that happens while you’re actively writing code. It’s optimized for human-in-the-loop development where you’re in the driver’s seat.
Claude Code handles discrete autonomous tasks: multi-file refactors, PR creation, issue resolution, test generation, and anything that requires reasoning across your entire codebase without hand-holding. It operates in your terminal and is designed to run tasks end-to-end with minimal interruption.
GitHub Actions provides the trigger layer — the CI backbone that fires Claude Code on specific events: `@claude` mentions in PR comments, new issues, failed test runs, or scheduled maintenance jobs.
The dominant 2026 practitioner pattern isn’t Cursor or Claude Code. It’s both, with a clean handoff. Claude Code went from zero to the #1 most-loved AI coding tool (46% developer love score) within eight months of its May 2025 release — ahead of Cursor at 19% and GitHub Copilot at 9% — precisely because it fills the autonomous task gap that IDE-native tools can’t (blog.exceeds.ai).
The handoff rule is simple: if you’d write a detailed Jira ticket to describe the work, it’s a Claude Code task. If you’d explain it to a pair programmer sitting next to you, it’s a Cursor task.
Writing a CLAUDE.md That Actually Gets Followed (The Three-Layer Structure)
Your CLAUDE.md is the system prompt for every Claude session in your repo. Vague instructions aren’t followed — they’re silently ignored. The three-layer structure fixes that.
Layer 1: Project orientation
What this codebase does, who uses it, and what “done” looks like. Claude needs this to make reasonable defaults when your instructions don’t cover an edge case.
“`markdown
Project
E-commerce checkout service. Node.js + TypeScript. PostgreSQL via Prisma.
Primary users: internal checkout team and external payment partners.
“Done” means: tests pass, no TypeScript errors, PR description updated.
“`
Layer 2: Architecture decisions
The non-obvious choices that would take a new engineer a week to discover. Document them explicitly so Claude doesn’t reverse-engineer the wrong conclusion.
“`markdown
Architecture
- Use the repository pattern for all DB access — never query Prisma directly in route handlers
- Auth is handled upstream by the API gateway — never add auth middleware here
- All monetary values in cents (integer), never floats
- Feature flags via LaunchDarkly SDK, not environment variables
“`
Layer 3: Tool routing
Explicit rules for when Claude should use which tool, run which command, and avoid which patterns. This is where most CLAUDE.md files are completely blank.
“`markdown
Tool Routing
- Run `npm test` after any change to /src — do not skip
- Use `gh pr create` for PRs — never commit directly to main
- Format with `prettier –write` before marking any task complete
- Do NOT modify files in /generated — these are auto-generated from schema
“`
The three-layer structure is the single biggest lever on output quality. A CLAUDE.md missing any of the three layers leaves gaps that compound across every task. Commit it to version control so every team member and every CI runner works from the same context.
Hooks vs. Skills — The Difference Between “Maybe” and “Every Single Time”
This is the most commonly misunderstood concept in the agentic coding pipeline, and getting it wrong costs you reliability.
Skills are probabilistic. They’re capabilities Claude invokes using its own judgment. Skills fire when Claude decides they’re appropriate — which makes them powerful for flexible, context-aware behavior, and useless for anything that must happen without exception.
Hooks are deterministic. They’re shell scripts wired to specific events in Claude’s execution loop. They fire every time, regardless of what Claude thinks.
Claude Code exposes four hook types:
| Hook | When it fires | Example use |
|——|————–|————-|
| `PreToolUse` | Before Claude calls any tool | Block writes to protected files; run a security scan |
| `PostToolUse` | After a tool call completes | Run `eslint` after every file edit |
| `Stop` | When Claude finishes a task | Run the full test suite; fail the task if tests are red |
| `prompt` / `agent` | On session or sub-agent start | Inject dynamic context; set environment variables |
Here’s a minimal `PostToolUse` hook that runs ESLint after every file write:
“`json
{
“hooks”: {
“PostToolUse”: [
{
“matcher”: “Write|Edit”,
“hooks”: [
{
“type”: “command”,
“command”: “npx eslint –fix $CLAUDE_TOOL_ARGS_PATH && echo ‘Lint passed'”
}
]
}
]
}
}
“`
And a `Stop` hook that blocks task completion if tests fail:
“`json
{
“hooks”: {
“Stop”: [
{
“hooks”: [
{
“type”: “command”,
“command”: “npm test || (echo ‘Tests failed — task incomplete’ && exit 1)”
}
]
}
]
}
}
“`
The rule: anything that must always happen goes in a hook. Anything that should happen when relevant goes in a skill. If you’re relying on Claude to remember to run your linter, you’ve already lost.
Wiring Claude Code Into GitHub Actions: A Copy-Paste Workflow With Security Defaults
Most GitHub Actions guides for Claude Code show you `@claude` and stop there. The production version requires more care. Here’s a workflow with correct permissions and security hardening baked in:
“`yaml
name: Claude Code Agent
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
permissions:
contents: write
pull-requests: write
issues: write
id-token: write
jobs:
claude-agent:
# Block fork PRs from accessing secrets
if: |
github.event.repository.fork == false &&
contains(github.event.comment.body, ‘@claude’)
runs-on: ubuntu-latest
steps:
# Pin by commit SHA — never use floating tags in production
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
- name: Run Claude Code
uses: anthropics/claude-code-action@a57ef8f8f19b8e7b2aff0c26fc3fb6d1f7f7b49a
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
github_token: ${{ secrets.GITHUB_TOKEN }}
claude_md_path: .claude/CLAUDE.md
“`
Three security defaults you must not skip:
- Pin actions by commit SHA, never by tag. Tags are mutable — a compromised `@latest` can execute arbitrary code in your pipeline.
- Block fork PRs from triggering Claude Code. External contributors should never have access to your `ANTHROPIC_API_KEY`.
- Use least-privilege job permissions. Only grant what the job actually needs — `contents: write` and `pull-requests: write`. Don’t use `write-all`.
For multi-repo organizations, store `ANTHROPIC_API_KEY` as an organization-level secret scoped to specific repositories, rather than duplicating it across every repo’s settings.
Task Structuring for Agentic Work: The State Machine That Keeps Agents From Going Off-Script
Autonomous agents drift when tasks are ambiguous. A state machine turns a vague task into a series of checkpoints with explicit pass/fail criteria. Here’s the eight-stage model that works in practice:
“`
INTENT → SPEC → PLAN → IMPLEMENT → VERIFY → DOCS → REVIEW → RELEASE
“`
Each stage has a definition of done:
- INTENT: Written as a one-paragraph brief with explicit success criteria. If you can’t write success criteria, the task isn’t ready.
- SPEC: Claude produces a technical spec listing affected files, edge cases, and assumptions. You approve or correct before implementation starts.
- PLAN: Claude lists specific changes in order. A deterministic hook verifies no protected files are in scope.
- IMPLEMENT: Claude makes changes. PostToolUse hooks run lint and type checks after every edit.
- VERIFY: The Stop hook runs the full test suite. Task cannot advance if tests fail — this is a hard gate, not a suggestion.
- DOCS: Claude updates README, changelog, and inline comments. A hook checks that relevant docs files were touched.
- REVIEW: PR is created with a structured description. A human reviews before merge.
- RELEASE: Merge and deploy. The agent updates the issue with a completion summary.
The most expensive thing Claude Code can do is implement the wrong spec correctly.
Approximately 4% of all GitHub commits are now authored by Claude Code alone (Anthropic, 2026 Agentic Coding Trends Report). That’s a significant volume of code shipping without a human at every step — which is exactly why deterministic gates between stages aren’t optional.
The Anti-Patterns That Kill Agentic Pipelines (And How to Catch Them Early)
Three anti-patterns account for the majority of agentic pipeline failures in practice.
Over-engineering multi-agent systems
Multi-agent architectures are powerful but expensive. Sub-agents consume 100K+ tokens internally but return only 1,000–2,000 tokens to the parent. Spinning up a sub-agent for a task a single well-prompted Claude Code session could handle burns budget and adds failure surface area.
Start with a single agent. Add sub-agents only when a task genuinely requires parallel execution or isolated context — not because the diagram looks sophisticated.
Skipping Verification
AI-assisted code can increase issue counts approximately 1.7× without governance and review (getpanto.ai). Bypassing your Stop hook “just this once” to hit a deadline is how AI-generated bugs accumulate silently across sprints.
Every task must hit the Verify stage. That’s the whole deal.
Pattern Rot
This one is subtle and compounds over time. Claude Code introduces a new pattern — say, a revised error-handling convention. The old pattern isn’t removed. Future Claude sessions see both patterns in the codebase and copy whichever appears more frequently. Over several months, your codebase develops architectural drift that’s expensive to untangle.
The fix is a scheduled refactor task. Once a sprint, run:
“`
@claude Audit the codebase for duplicate patterns. List any cases where
two approaches solve the same problem. Propose which to standardize,
then open a GitHub issue.
“`
This creates a feedback loop that keeps the codebase coherent even as AI-generated code accumulates. Skipping this step is how good pipelines slowly become bad codebases.
Sprint Checklist — Ship Your Agentic Pipeline in Five Working Days
This is the full setup in sequential order. Each item should take no more than a few hours.
Day 1 — Foundation
- [ ] Create `.claude/CLAUDE.md` with all three layers (orientation, architecture, tool routing)
- [ ] Add `settings.json` to the project root with hook stubs for PostToolUse and Stop
- [ ] Commit both to version control and share with the team
Day 2 — Hooks
- [ ] Implement PostToolUse lint hook (ESLint/Prettier on every file write)
- [ ] Implement Stop hook (full test suite on task complete; exit 1 on failure)
- [ ] Test locally: run a Claude Code task and verify hooks fire correctly
Day 3 — GitHub Actions
- [ ] Add the workflow file to `.github/workflows/claude.yml`
- [ ] Store `ANTHROPIC_API_KEY` as a repository or org-level secret
- [ ] Test with a `@claude` mention on a draft PR
Day 4 — Task Structuring
- [ ] Add a `## Task Protocol` section to CLAUDE.md defining your state machine stages
- [ ] Run one real task using the INTENT → SPEC → PLAN flow
- [ ] Confirm that the Stop hook blocks advancement when tests fail
Day 5 — Team Rollout
- [ ] Demo the pipeline live with a real task
- [ ] Define the Cursor/Claude Code split for your team’s specific workflow
- [ ] Schedule a recurring 30-minute “pattern audit” sprint ceremony to catch pattern rot early
Developers using AI coding tools save an average of 3.6 hours per week, and daily users merge approximately 60% more PRs (getpanto.ai). That payoff is real — but only if the pipeline holds up past the first sprint.
Build the System, Then Trust It
A reliable agentic coding workflow setup isn’t a collection of tools — it’s a system of explicit contracts between humans, agents, and CI. CLAUDE.md tells the agent what matters. Hooks enforce the rules that can’t be optional. GitHub Actions brings automation into your existing review flow. The state machine keeps tasks from drifting into something nobody asked for.
The teams that get lasting value from agentic coding treat it like infrastructure: designed deliberately, maintained regularly, and improved based on what breaks — not what looked good in a conference demo.
Pick up the sprint checklist, commit a CLAUDE.md by end of day, and ship the first automated PR before Friday. That’s the only way to know if your pipeline will hold.