Internal platform engineering teams use generative AI to speed up delivery, but arbitrary prompting and generic retrieval rarely hold up inside large, brownfield codebases.
Akvelon engineers built a spec-driven, guardrail-backed delivery architecture on Anthropic's Claude that carries a feature from a scattered requirement all the way through to a resolved production incident.
About the project
The client's platform engineering team was managing a large brownfield ecosystem while under pressure to accelerate feature delivery. Like many enterprise teams, they had already tried ad hoc prompting and general-purpose retrieval-augmented generation. Both ran into the same limits most teams hit at this scale: long-context bloat, hallucinated architectural links, rising API token costs, lack of guardrails, and inconsistent use.
Akvelon's team set out to replace that ad hoc pattern with a more disciplined approach: a specification-first workflow paired with an internal, AI-optimized context layer. The same approach carries through every stage, from requirement gathering to incident response.
The challenge: AI use that didn't scale with the codebase
Generic AI assistance treats every request the same way, regardless of how much undocumented context the codebase holds. Requests to platform engineering rarely arrive as clean requirements – they're scattered across email threads, Notion brainstorms, Confluence architecture decision records, and Figma mockups.
Engineers spend real time reconstructing intent before they can start any work. Every additional AI query against the raw codebase adds context-window overhead and cost.
Our Client’s team needed a workflow that imposed structure on the input side, not just a faster way to generate code.
Technical approach: a spec-driven, guarded delivery architecture
Rather than treating Claude as a general-purpose coding assistant, Akvelon built three connected phases, each with its own checkpoint, that carry a request from raw input to verified resolution.
From fragmented inputs to rigorous specs
A Claude-based PRD agent parses raw text from emails, Confluence pages, and meeting notes, while separately extracting layout and component relationships from Figma files. Before anything reaches a sprint board, a product manager's human-in-the-loop checkpoint reviews and corrects the generated specification.
The pipeline generates JIRA Epics and Stories only after that approval is granted. It deliberately stops at that level of granularity, breaking work into individual tasks, and it stays the engineering team's call.
When upstream requirements change, an update flow maps the delta against active tickets and adds revision notes rather than discarding existing work.
Guardrails in the development loop
With an approved specification in place, development work stays bound to it. Akvelon implemented Claude Code Hooks, configured in the agent's settings and tied to the team's validation logic, to enforce this at execution time.
A PreToolUse hook checks every tool call, file edit, or shell command against a policy-as-code engine (Open Policy Agent) and static analysis scripts before it runs. Violations are blocked and fed back into Claude's context so it can self-correct. A PostToolUse hook injects runtime context, such as a file mutation notice, without spending tokens to reread files.
For higher-risk changes (VPC configuration, production database schemas, IAM policy) a developer human-in-the-loop checkpoint pauses the session. Execution resumes only after a human reviews the diff and approves it.
AI-accelerated incident response
The same specification-and-checkpoint discipline carries into operations. When a production alert fires, a Claude-based incident agent pulls live telemetry from Datadog and AWS (CloudWatch, CloudTrail, ECS/EKS). It then cross-references that telemetry against historical post-mortems and runbooks in Confluence and the team's internal context layer.
The agent correlates the alert with recent code changes and produces a root cause analysis. It also drafts a candidate remediation script for human review, with approved fixes pushed back into JIRA as high-priority updates to close the loop.
Keeping AI operations lean: context and token optimization
Running Claude across all three phases at enterprise scale adds real token overhead if left unmanaged. Akvelon's team addressed it with four techniques, applied consistently throughout:
- Bottleneck profiling. Token and cache-miss audits identified blind, sequential directory scanning as the largest cost driver. That finding moved the team away from raw-text codebase ingestion entirely.
- LLMWiki and Graphify context compression. Internal documentation was restructured into dense, prose-stripped Markdown. A deterministic AST map, built with Graphify, lets Claude query a lightweight graph.json for targeted lookups instead of scanning source trees – without losing accuracy.
- Task-driven subagents. Instead of accumulating context across a long session, an orchestrator spawns short-lived, single-purpose subagents. For example, a database schema validator, an AWS log parser. Each runs in a minimal, isolated window and self-terminates once its task is done.
- Static skills and prompt caching. Corporate coding rules, security policies, and infrastructure guidelines were split into modular, static instruction sets. Variable data, such as a specific JIRA story, is appended to the end of each query, so the static portion stays cache-friendly and repeat queries cost less.
Business value
Structuring AI assistance around specifications and enforced checkpoints paid off across the full delivery lifecycle. Requests turn into working plans faster, and production issues get resolved faster, too.
Where this is most valuable
This approach is especially useful for teams working in a specific set of conditions:
Conclusion & what's next
Specifications and enforced checkpoints, rather than the underlying model, kept this workflow reliable at enterprise scale. Akvelon's team is extending the architecture further: deeper integration between the incident response layer and the specification pipeline, so operational learnings feed back into how future work gets scoped.
