~/douglas-montanus
← All posts

Agentic Dev Harness: Next.js + Node on Jira, GitHub, ECS & RDS

November 12, 2026 · 9 min read

AIAgentic SystemsClaude CodeAWSCI/CD

The agent proposes; the harness verifies. Claude writes stories, code, and tests, but every claim it makes ("done," "passes," "secure") must survive a check it doesn't control.

The loop has eight stages. Four are where Claude reasons: Jira story drafting, the spec agent, the build agent, and the AC review agent. The others are deterministic gates (hooks, CI, deploy checks) that Claude can't talk its way past. Failures, alarms, and review findings flow back into Jira as new tickets.

Claude proposes; deterministic gates verify

  [Jira story]  ─►  [Spec agent]  ─►  [Build agent]  ─►   Local hooks
   Story +          AC to failing      Code in a          Lint, types,
   testable AC      tests              worktree           tests
       ▲                                                      │
       │       ┌──────────────────────────────────────────────┘
       │       ▼
       │   GitHub CI  ─►  [AC review agent]  ─►   Deploy     ─►   Observe
       │   Tests and       Checks each AC         ECR to ECS      Logs and
       │   scans                                  + RDS           alarms
       │                                                             │
       └─────── failures, alarms and review findings ◄───────────────┘
                become new Jira tickets

  [ ] = Claude reasons        plain = deterministic gate or system

Work runs left to right across the top row, then the bottom. The feedback path sends production and review signals back into Jira.

1. Context layer

Agents fail mostly from missing context, not weak reasoning, so this layer is the most underrated part.

  • CLAUDE.md in the repo root: architecture rules, folder conventions, the commands that matter (pnpm test, pnpm db:migrate), and what it must never do, such as editing applied migrations or touching infra/prod. Add nested CLAUDE.md files in apps/web (Next.js) and apps/api (Node) for area-specific rules.
  • Skills: packaged procedures Claude loads when needed, such as "write a migration safely," "add an API endpoint with OpenAPI + zod validation," or "write a Playwright test from an AC."
  • MCP servers:
    • Atlassian/Jira, to read stories and post status.
    • GitHub, for PRs, checks, and comments.
    • Optionally a read-only Postgres MCP pointed at a dev RDS snapshot, to inspect schema.
  • Contracts as the source of truth: an OpenAPI spec for the Node API, with types generated into the Next.js client. If frontend and backend drift, the build breaks.

2. Story creation and refinement (Jira)

Your approval of the story is human gate #1, and the cheapest place to catch a wrong requirement.

  • A story-writer agent (a Claude Code subagent or a Claude Agent SDK script) turns a rough epic into stories. Acceptance criteria use Given/When/Then, because each line has to be mechanically checkable.
  • A Definition of Ready check confirms every AC is tagged with a test type (unit, API, e2e) and the story names its data and security impact. Stories that fail get flagged instead of picked up.

3. Spec to build (Claude Code)

Tests come first, and each agent gets only the tools its job needs.

  • Spec agent: reads the story through the Jira MCP and writes a test plan mapping each AC to a named test. It writes the failing tests first.
  • Build agent: works on a branch named after the ticket (feat/PROJ-123-…) in an isolated worktree or container, and implements until the AC tests pass.
  • Subagents with narrow jobs keep context clean: db-migration, api, ui, test-writer, security-reviewer.
  • Permissions in .claude/settings.json:
    • Allow pnpm test, git, and docker compose.
    • Deny aws against prod, reading .env*, and git push --force.
    • The agent never holds prod credentials.

4. Local gates (hooks)

Hooks are deterministic scripts Claude Code runs on events. They are not suggestions.

  • After edits: prettier, eslint, and tsc --noEmit on touched files.
  • Before a bash command: block dangerous commands (DROP, rm -rf, terraform apply).
  • On stop: run the affected unit tests. If they fail, the agent can't declare itself done.

5. CI gates (GitHub Actions)

The PR triggers the real verification. Make each of these a required status check under branch protection.

GateWhat it runsWhat it catches
Build and typesLint, typecheck, Next.js buildBroken code, type drift
Unit testsVitest/Jest, coverage threshold on changed filesLogic regressions
API integrationTests against real Postgres (Testcontainers or service container)RDS behavior that mocks hide
Migration checksApply, roll back, reapply on a fresh DB; lint for destructive opsUnsafe schema changes (human label required to merge)
E2EPlaywright against a preview environment, one spec per UI-facing ACBroken user flows
SecurityCodeQL/Semgrep, npm audit/Dependabot/Snyk, gitleaks, Trivy, Checkov/cdk-nagVulns, leaked secrets, insecure infra
ContractOpenAPI diffBreaking API changes without a version bump

6. AC validation

Green tests only prove the agent's own tests pass, not that the story is done. A separate AC review agent, which didn't write the code, runs on the PR through the Claude Code GitHub Action. It:

  1. Pulls the ACs from Jira.
  2. Maps each AC to the test(s) that cover it and to the diff.
  3. Posts a checklist comment on the PR: ✅ covered, ⚠️ weakly covered, ❌ missing.
  4. Fails a status check if any AC is ❌.

It also runs a security-focused pass: authz on new endpoints, input validation, SQL built from strings, secrets in logs. Human code review stays as gate #2. The agent narrows what you look at rather than replacing you.

7. Deployment (AWS ECS + RDS)

Build one image, promote it unchanged, and let alarms roll it back.

  • Credentials: GitHub → AWS via OIDC, with no long-lived keys. Use a separate IAM role per environment; the prod role can only be assumed from main with a GitHub Environment approval.
  • Images: build once, push to ECR tagged with the commit SHA, and promote the same image across dev → staging → prod.
  • Migrations: run as a one-off ECS task before the service update. Use expand/contract so old and new app versions both work against the schema during rollout.
  • ECS rollout: CodeDeploy blue/green, or rolling with the deployment circuit breaker. CloudWatch alarms (5xx rate, p95 latency) trigger auto-rollback.
  • Ephemeral previews per PR: an ECS service against an RDS snapshot clone, or a schema-per-PR on a shared dev cluster, torn down on merge. Playwright and the AC review agent run against it.
  • Secrets: stored in Secrets Manager and injected into task definitions. RDS uses IAM auth or rotated secrets.

8. Feedback loops

Four loops at different speeds are what make this a harness rather than a pipeline.

LoopSpeedTriggerWhat happens
InnerSecondsHook outputType and test errors go straight back to the agent mid-task
PRMinutesCI failure or @claude review commentAgent fixes and pushes again; capped at about 3 attempts, then escalates to you
ProdHoursCloudWatch alarm or Sentry errorWebhook creates a Jira bug with logs attached; it flows through the same pipeline
HarnessOngoingA repeated agent mistakeAdd a CLAUDE.md rule, a skill, or a new CI check

Jira sync: status moves automatically (In Progress on branch, In Review on PR, Done on prod deploy), the PR links back to the story, and the AC checklist is posted to the ticket.

Telemetry across the loop

You can't govern what you can't see. Every agent run should be traceable back to the story it was working on.

  • One ID per story: carry the Jira key (PROJ-123) through the branch, every agent run, the PR, the CI jobs, and the deploy. One query should show everything that happened for a story.
  • Per-run telemetry: enable Claude Code's OpenTelemetry export (CLAUDE_CODE_ENABLE_TELEMETRY=1) and send it to a collector that feeds CloudWatch or Grafana. Record input and output tokens, cost, tool calls, duration, retries, and outcome for each agent.
  • Tie spend to outcomes: track cost per accepted story, first-pass CI rate, and how many PR-loop attempts a story needed. Token counts alone don't tell you whether the code was any good.
  • Keep sensitive data out: no prompts, source code, or secrets in telemetry by default.

I go deeper on this in Measuring AI Coding Agents.

Token budgets: stopping runaway agents

An agent can keep rerunning a failing test, rewriting the same function, or pulling more context long after it has stopped making progress. A prompt that says "be efficient" won't stop that. The harness has to.

  • Limits live in the harness, not the prompt: the orchestrator or CI job owns the counters and checks them before every model call.
  • Budget per story: size it during the Definition of Ready check and split it across the spec, build, and review agents. Subagents draw from their parent's budget, so together they can't exceed it.
  • Hard caps: a maximum turn count per run (--max-turns in headless mode, maxTurns in the Agent SDK), a wall-clock limit on the job (timeout-minutes in GitHub Actions), and the existing cap of about 3 PR-loop attempts.
  • Detect lack of progress: the same test failing repeatedly, an unchanged diff, or identical tool calls hitting a warning threshold trigger a checkpoint where the agent summarizes and re-plans. Hitting the hard limit stops the run.
  • Stop safely: push the work to the ticket branch, post a summary to Jira (what's done, what's left, the last failing test, tokens spent), move the ticket to Blocked, and escalate to a human. Running out of budget never merges anything.

More on this in Putting Guardrails Around Autonomous AI Coding Agents.

Human gates and build order

Three human approvals remain; everything between them can run unattended.

  1. The story and its acceptance criteria.
  2. The PR merge.
  3. The prod promotion, plus any destructive migration.

If you're building this, here's the order I'd suggest:

  1. CLAUDE.md, hooks, and CI gates. These pay off even when you write the code yourself.
  2. The AC review agent.
  3. Jira automation and per-PR preview environments.