DEV Community

Muazzam
Muazzam

Posted on

How I actually build software with AI agents

Most of the code I ship now is written with an agent (Claude Code). The problem I kept hitting early on was not that the agent wrote bad code, it was that it wrote different code every time, because every session started from zero and I was re-explaining the same house rules in every prompt.

What fixed that was not better prompts. It was building a small system around the agent: the rules it follows, the systems it can reach, how work gets split up, and who reviews what. This post is how that looks on my machine today.

House rules as skills

Claude Code has "skills": a folder with a SKILL.md file that the agent loads when the task matches its description. I use them for anything I would otherwise explain twice. Right now I have skills for how our Astro static sites are structured, a WordPress pre-launch checklist, an audit for inherited WordPress sites, a long Figma-to-Bricks playbook, a SaaS starter, wiring forms to a lead-capture API, and a library of reusable page sections.

The point is that a skill is not a prompt. It is a written standard, with the reasons, that the agent applies the same way on every project. For example, this is from the launch checklist:

Every form gets ONE live test submission (coordinate with the client if it
emails/notifies real staff). Verify: success message, error path (temporarily
break the endpoint or submit invalid), required-field validation, and where the
data lands. A form that "renders fine" is not a tested form.
Enter fullscreen mode Exit fullscreen mode

That last sentence is there because I have shipped forms that rendered fine and delivered nowhere. Now the agent cannot call a site ready without a real submission.

The SaaS starter skill is stricter. Every new app with a login starts as a fork of my own multi-tenant base (Postgres row-level security, workspaces, roles, audit log), and the skill has a "red flags, stop" list:

- Writing a `User`, `Organization`, or `Role` model → it exists, fork the base
- "I'll add multi-tenancy later" → later costs 10x; it is free today
- Writing `WHERE workspace_id = ...` in a router → RLS already did it; a manual
  filter hides a broken policy
Enter fullscreen mode Exit fullscreen mode

That list exists because before the base, five of my apps each had their own hand-rolled tenancy. The skill even names them and says "do not add a sixth". An agent left alone will happily write a User model in the first five minutes. With the skill loaded it says "this is an app, so it starts as a fork" before writing any code.

Two things I learned about writing these:

Skills should carry the facts that docs get wrong. The lead-capture skill has a reference table for the ingest URL and auth headers, and right under it: "Trust this table over the repo docs", because the project's own integration doc shows a stale path. I found that by reading the backend source, and I don't want to find it again.

Skills should grow from real projects. The Figma-to-Bricks playbook started small and is now over 6,000 words, almost all of it gotchas I hit while building: SVG exports that render at 300×150 because of their headers, transparent PNGs that turn black when converted to JPEG, duplicate element ids that cause a 500. One line in it says my guessed section names "were wrong ~30% of the time until I looked", which is why the playbook now says to screenshot every section before naming it. When a project teaches me something, the lesson goes into the skill, and the next project starts with it.

Right now the skills live only on my machine. Everything is backed up to the cloud regularly, so if I lose this laptop I can set it all up again, but they are not in git yet. Moving them, and my other working projects, into git repos is next on my list. Skills are code that changes how the agent behaves, so they should have history and review like any other code.

Real systems over MCP

The second part is giving the agent access to real systems instead of pasting context into the chat. I have MCP servers set up for a WordPress management server (it can run PHP and WP-CLI against a site, read and write files in a sandbox), a CRM I use for clients and projects, and my Home Assistant at home.

This changes the kind of work I can hand over. On a WordPress site the agent can inspect the actual database before it plans anything. The audit skill tells it to grep custom plugins for hardcoded keys, map every external API call, and check blog_public, all against the live install. The launch checklist runs a PHP query over every page's builder content to find # placeholder links. I don't have to describe the site. The agent just looks at it.

Everything goes through permission prompts. The agent asks before it writes, and the skills say what it should not do on its own. The launch checklist, for example, says not to quietly fix outward-facing things like redirects, analytics or production API keys, and to confirm with me first.

Sub-agents for research and audits

For research and audits I fan work out to sub-agents, one per site, server or source. Each one reads its own pile of files and logs and sends back only a conclusion, so my main session doesn't fill up with raw output.

A recent example is which.pk, a consumer advice site I'm building for Pakistan, starting with property. One page can need a dozen facts: prices, fees, rules, which authority does what. I split that across agents. Some do the research, others go back and confirm each fact against a second source, and another finds images we can actually use. What comes back to me is the facts with their sources, and the ones that could not be confirmed are marked. I decide what goes on the page. For an advice site that's the whole point, a wrong fact is worse than a missing one.

On my own products the same idea is part of the process. The RepoCMS repo's working guide says non-trivial work goes brainstorm, written spec, written plan, then sub-agent execution with a spec and quality review per task, then the full test suite, then a commit per task. The plan files live in the repo, so I can read what the agent was going to do before it did it.

The sub-agents do the reading. I make the decision and write down the trade-off.

Review stays human

Agents scaffold, refactor, and try alternatives I wouldn't have time to try by hand. I read every diff. Anything that touches production, payments or client data goes through me, not just through tests.

The skills support this too. The Figma playbook has a "golden rule: never trust, always verify", and it means screenshotting the real rendered page at desktop and mobile after every section, not batching three sections and then looking. It also tells the agent to report honestly: broken screenshots, wrong first attempts and API mismatches go in the summary. I would rather read "this didn't work the first time" than find it myself later.

Review is also about steering, not only reading the final diff. Agents can wander. I once asked about a broken link on a single page, and the agent started working through a sitemap with more than 500 pages to check every link on the site. That's not what I asked for, and it would have burned time and tokens for nothing. I stopped it and pointed it at the one page. Watching what the agent is doing, and interrupting early, is part of the job.

What I'd do differently

I'd start writing skills earlier. For a long time I kept the rules in my head and in old projects, and the agent kept rediscovering them. The first version of a skill can be ten lines. It only has to be better than explaining it again.

Top comments (1)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.