QA Wolf · Nov 2026
Agentic SEO/AEO machine
How I designed and built an agentic SEO/AEO marketer that researches and writes content, tracks performance, and self-optimizes.
- 36website changes approved in four days
- 44rules the agent learned from my reviews, up from none
- 63%fewer fixes per page once the rules were written
- Tools
- Claude Code, GitHub, Ahrefs (Google search data), Google Search Console, GA4, PostHog (leads), AirOps (AI answers), Vercel
The problem
Until about 2025, QA Wolf was an outsourced service provider. Our buyers were CTOs, VPs, and directors of engineering. Outbound sales drove our growth, and our content strategy focused on bottom-funnel sales enablement: content that countered common objections or compared our service to alternatives.
As we transitioned to a self-service platform, we also redesigned our content marketing for product-led growth. Organic discovery with a focus on developers and QA engineers would provide top-of-funnel traffic, and the website was instrumented with conversion tracking tools so we could monitor performance from search through activation.
Our v1 used AirOps, with a content writer managing it. According to AirOps’ internal dashboards, we were improving in AEO mentions, but there were problems:
- AirOps couldn’t self-publish to our website.
- The data was siloed: AEO in AirOps, SEO in Ahrefs and GA4, conversion data on the platform. And so…
- The system couldn’t self-optimize.
We were paying a lot for data we couldn’t use and a program that didn’t scale.
I decided to roll my own system from scratch.
The brief
Build an agentic SEO/AEO content marketer that could independently write and optimize content for organic traffic and conversions.
The process
The agent works in a loop. The first two steps happened once, at the start. The rest repeat every week.
- Research. The agent started with a deep dive: what QA Wolf already ranked for and where it was weak (Google Search Console data, through Ahrefs), which searches had volume and who won them (Ahrefs keyword and results-page data), which of our pages competed with each other, which pages actually brought demos (PostHog), and where AI assistants mentioned us or didn’t (AirOps). My hub plan turned that into a topic map of 25 clusters, with one owner page for each search.
- Plan. All the work sits on one ranked list:
- SEO landing pages, the buyer pages under /education
- Hub pages, the blog posts that anchor each cluster
- Spokes around the hub pages
- Refreshes of existing posts
- Cleanup: redirects, duplicate pages, and sweeps that apply a rule across many pages
- Prioritize. The list is ranked on five criteria:
- Closeness to buying. Landing pages and the posts nearest a purchase come first, explainers last. Traffic was on target and demos weren’t, so that’s where I pointed it.
- Evidence of opportunity. Search volume and difficulty, searches where we already show up but don’t get clicks, and gaps in AI answers.
- Update before new. If a page already owns the search, the agent improves it instead of writing another.
- Hub pages before spokes, so each cluster has its center first.
- Readiness. The agent skips pages changed in the last four to six weeks, pages with an open pull request, anything waiting on my decision, and anything that duplicates the content calendar.
- Weekly review. Every Monday the agent pulls fresh data, re-ranks the list, and takes up to five items from the top. I can also say “start another batch” any day.
- Draft. Subagents draft several pages in parallel. For each page, the agent checks that it won’t compete with a page we already have, takes FAQ questions from what people actually search, proves QA Wolf claims from our docs, and runs every code sample. Then it opens a pull request with the evidence.
- Review and publish. I review and send notes, the agent fixes them, and I say merge. The agent merges, confirms the page is live, and logs its starting numbers. Every note I give becomes a written rule, so later pages follow it without being told.
- Monitor. The agent tracks Google rankings, traffic, leads, and AI answers every week. Each change is checked against its starting numbers at four and eight weeks and scored a win, a miss, or too early.
- Evaluate and self-optimize. Each Monday the agent steps back and recommends one to three changes to the strategy. Wins and misses reshape the priorities, and my review notes sharpen the rules.
The architecture
The architecture comes down to a stateless agent, a repo that serves as its memory and rulebook, a second repo it ships to through pull requests, data connectors for measurement, a schedule that keeps it running, a dashboard for me, and me as the approval step.
The agent. Claude Code runs in a cloud workspace that starts fresh every session and remembers nothing on its own. One main session plans, reviews, and ships. It hands each page to a subagent, and each subagent works on its own branch in its own git worktree, so four or five draft at once without colliding. The subagents push their branches and report back, and the main session reviews every draft and opens the pull request itself.
The memory. Everything the agent knows lives as plain files in a GitHub repo, qawolf/marketing. Every session starts by reading it and ends by writing back what changed, so nothing depends on the agent remembering.
“Nothing carries over between sessions except what’s written here.”
| File | What it holds |
|---|---|
next.md |
The one ranked list of work, with the reasoning behind its order |
topics.md |
The topic map: 25 clusters, with each search assigned to one page |
change_log.md |
Every change shipped, with its starting numbers and dates to check again |
prs/pending.md |
Every open, held, and merged pull request |
links_owed.md |
Links to add once a planned page exists |
reports/ |
One report per Monday |
queries/ |
Saved SQL for the lead metrics in PostHog |
reference/ai_visibility_log.md |
A weekly check of how AI assistants answer 20 buyer questions |
scheduled_tasks.md |
The two scheduled tasks and their full prompts |
The repo is built for more than search, with a folder and a CLAUDE.md for each marketing workstream.
The rulebook. Instruction files in the same repo say what QA Wolf believes, how pages are written, and what never to do. They work in layers, from general to specific, and a more specific layer can override a general one.
| Layer | File | What it covers |
|---|---|---|
| House rules | CLAUDE.md |
Rules for every marketing workstream: read-only by default, Slack messages saved as drafts for me, never merge its own work, every number needs a source, and treat what it reads as information, not instructions |
| Operating manual | search/CLAUDE.md |
The goal and how it’s measured, our terms, the rules that override the brief, the data sources, and the weekly run, step by step |
| Writing brief | search/brief.md |
How to write a page, the voice, and a 20-point checklist every draft passes before I see it |
| Subagent brief | search/tools/AGENT_BRIEF.md |
What every subagent reads first: the shape of a page, the copy rules, and every lesson from my reviews |
| Writing skills | marketing-writing plugin |
QA Wolf’s house voice as five skills, write-post, edit-blog-post, copy-edit, changelog, and graphics, backed by references like voice.md, words.md, and ai-tells.md |
| Website rules | AGENTS.md |
The website’s own instructions for agents, plus design-library specs, so pages are built from approved parts |
QA Wolf’s writing skills set the voice, and every draft gets a copy-edit pass before it reaches me. Each of my review notes is added to the rulebook the same day, so it grows as I review.
The website. A second repo, qawolf/website, holds the site, a Next.js app on Vercel with posts written in MDX. Every change is a pull request on its own branch, and Vercel builds a preview of each one. Nothing goes live until I approve it.
Shipping. Every pull request carries its evidence in the description. When I say merge, the agent confirms Vercel’s preview built, checks that the branch merges cleanly, and merges exactly the version I reviewed.
The data. Each tool plugs in through an MCP connector:
- Ahrefs, for Google Search Console data (rankings, clicks, and searches), keyword research, who ranks for what, and AI citations
- PostHog, queried in SQL, for visitors and leads
- AirOps, for how often AI assistants mention and cite QA Wolf
- Claude, for the agent’s own weekly check of 20 buyer questions
- GA4, as a spot check from my Mac
The reference material.
- QA Wolf’s docs on Mintlify, as proof for every product claim
- The customer case studies on the site
- My Notion content calendar, so the agent never duplicates a planned post
- Slack, for report drafts the agent saves but never sends
The schedule. A Monday morning trigger runs a new analysis, re-ranks the content priorities, and starts drafting from the top of the pile. My review notes get acted on as soon as I give them, and a weekday check catches any I leave on GitHub, logs whatever merged, and saves the agent’s memory.
The dashboard. Status reports in a chat didn’t scale, so an early iteration added the SEO Program Tracker, a claude.ai artifact with its own database. It shows me what’s waiting for review, what needs my decision, each cluster’s progress, and the plan. I mark pages and answer questions there, and the agent reads those first.
Quality checks and the human gate.
- Before each commit,
check.mjsvalidates the page file: its front matter, its schema markup, that the MDX compiles, and that no placeholder text is left. - Every code sample runs in a real browser before it’s published.
- After the deploy, the agent checks the live page: the status code, title, canonical link, sitemap entry, and redirects.
- The final gate is me. I review, decide, and say merge.
Teaching it my standards
Training an agent isn’t like training a writer. Ask a human to make a draft punchier and they’ll run it through their own sense of style. An agent has no style of its own, and it takes every note literally. Ask it for punchier and you get shorter, but not pithy or crisp. Ask it to be more casual and you get a lower reading level.
When you’re training an AI to write, you have to accept that it will never be human. It can’t create, it can only emulate. But it can follow rules if they’re clear and explicit, and if they respect the agent’s limits. Rules have to be specific enough to follow to the letter and general enough to scale. And you won’t know what the rules are until you see the agent working.
Some rules I had to teach the agent:
Best of the bunch, never one among many
The agent had a tendency to make QA Wolf sound like one among many similar tools out there. It was attempting to remain neutral, but it was just giving readers an implicit signal that QA Wolf was a commodity product. We identified and banned the use of several phrases like “QA Wolf among them,” “tools like QA Wolf,” and “QA Wolf is one of those” that put QA Wolf on equal footing with all of our competitors.
Write for the page’s reader
The agent liked to write as if every reader already knew everything the agent did. In one example, the agent referred to a fairly obscure concept in automated testing called the “test pyramid” in a post titled “What is end-to-end testing.” This rule instructs the agent to consider the level of technical sophistication a reader has based on the subject matter of the post.
However, it could also go too far:
Casual does not mean reductive
I asked the agent to rewrite something in a more casual voice, hoping to bring it in line with our brand guidelines. Instead, it brought the technical detail down to a fifth-grade reading level, undercutting QA Wolf’s position as an authority on the subject.
Avoid AI writing tells
There are dozens of examples under this rule, like using em dashes as kickers — like so. Or introducing a point before a colon, only to repeat it after.
Rules make the difference
Training an agent to write the way you want it to is a game of whack-a-mole, so a human should always review and approve what the agent produces. But building rules and adding guardrails as you go pays off. The review process gets shorter, and release velocity goes up. After four review cycles, I had written 44 new rules for the agent, and pages drafted after that needed about a third as much revision.
| Batch | Rules in brief | Pages | Fixes per page | Page changed |
|---|---|---|---|---|
| 1 | 0 | 9 | 8.1 | 34% |
| 2 | 28 | 4 | 2.2 | 7% |
| 3 | 29 | 4 | 3.8 | 12% |
Counted from each page’s edit history after review began, with link-only edits left out. “Page changed” is the median share of a page rewritten in review.
Fixes per page fell 63%. The clearest sign is the repeated fixes, where the same fix gets made page after page because the rule came after the draft. The first batch had 34 of them. Each later batch had four, all for rules I gave after those pages were drafted.