AI-Assisted Development

A stepwise guide for a new developer joining a team that uses coding agents (Claude Code, Cursor, etc.) as a core part of the workflow.

General Overview and Flow #

AI-assisted coding has sped up the rate of writing code. Most people are still not convinced of its advantages because the output generated by their coding agents is not what they expected. They call it AI slop or vibe coding because they are still coding like it's 2023.

Now that AI coding as a field has matured, there is no reason to stick to simply asking ChatGPT questions in a chat conversation and copy-pasting code.

In order to produce software at a faster pace than is humanly possible while maintaining correctness, you need to follow a structured path regardless of the tools you use. I recommend the following flow, which I developed using the framework provided by Matt Pocock from aihero.dev:

Write Great Tickets #

Everything starts here. A ticket is the prompt. Garbage in → garbage out. A great ticket means the agent can work independently, and you can review the result instead of hand-holding it through every line.

A great ticket contains:

• Goal — one sentence describing what the world looks like after this ticket is done.
• Context — links to the spec/PRD, relevant files, domain terms from CONTEXT.md, and any ADRs that constrain the solution.
• Acceptance criteria — bullet points that are testable. "The user can X" not "The code should Y."
• Blocking edges — which tickets must finish before this one can start.
• Size — fits in a single fresh context window. If the agent can't finish it in one session, the ticket is too big. Slice it smaller.

The pipeline that produces great tickets:

1. Grill the idea first — stress-test the plan with the grilling skill before writing anything down.
2. Capture the decision — use to-prd or to-spec to write a PRD/spec from the conversation. No interview — it synthesises what you already discussed.
3. Slice into tickets — use to-tickets to break the spec into tracer-bullet vertical slices, each sized for one context window, each with its blocking edges declared.

**Rule of thumb:** If you're tempted to start coding before writing a ticket, stop. Write the ticket first. The act of writing it reveals assumptions you didn't know you had.

Structuring Tickets #

Whether your engineering team uses Jira, GitHub Projects, or Azure DevOps, every ticket must follow a clean, standardized structure that provides unambiguous context to both human developers and autonomous AI agents. For deep enterprise specifications tailored specifically to Azure DevOps ticket fields (Epics, Features, PBIs, Tasks, and Bugs), visit Azure DevOps Ticket Standards.

Crucial Governance: AI-Generated Tickets & Mandatory Human Approval #

In an automated agentic workflow, it is trivial for an AI agent to generate dozens of tickets and add them to your project board. It is equally trivial for a worker agent to pick up an unvetted ticket and begin executing file modifications.

To prevent unvetted agent-to-agent feedback loops and ensure humans share accountability for ticket accuracy:

1. Mandatory AI Ticket Warning Header: Every ticket created or drafted by an AI agent MUST include the following explicit warning banner at the very top of its description:

   text Copy

   ==THIS IS AN AI-GENERATED TICKET. REQUIRES HUMAN APPROVAL. DO NOT WORK ON IT.==

2. Agent Refusal Protocol: Autonomous agents MUST inspect ticket descriptions before starting work. If the warning header above is still present, the agent MUST immediately refuse to execute the ticket, log a waiting notice, and halt until a human approves it.

3. Human Approval & Sign-Off: A human engineer must read the ticket, verify its scope, acceptance criteria, and blocking edges, remove the warning line, and replace it with the human approval sign-off:

   text Copy

   ==TICKET APPROVED BY: @name-of-human-reviewer==

Only when the ==TICKET APPROVED BY: @name-of-human-reviewer== header is present is an agent authorized to pick up the ticket and begin implementation.

Add Instruction Files #

Instruction files tell the agent how to behave in your codebase. They're the first thing the agent reads when it opens a project.

Where they go:

What to put in them (keep it short and stable):

• Project conventions — language, framework, package manager, test runner, linting setup.
• Commands — how to install deps, run tests, build, typecheck, lint.
• Key files — where the domain model lives (CONTEXT.md), where ADRs are (docs/adr/).
• Skills to use — "Always use /tdd for implementation. Use /code-review before committing."
• Gotchas — things that have burned agents before.

Example CLAUDE.md:

# Project conventions

- TypeScript, React, Next.js App Router, Vitest, Playwright
- `pnpm dev` to start, `pnpm test` to run tests, `pnpm typecheck` to typecheck
- Domain model lives in `CONTEXT.md`, ADRs in `docs/adr/`
- Always use /tdd for implementation
- Run /code-review before committing
- No `any` types. Prefer `unknown` + type guard.

**Keep it stable.** Don't put ephemeral instructions here. The instruction file is for things that are *always* true.

Write Great Skills #

A skill is a reusable instruction file (SKILL.md) that teaches the agent how to do one thing well. Skills live in ~/.agents/skills/<skill-name>/SKILL.md and are symlinked into ~/.claude/skills/ (Claude Code) or loaded via .cursor/rules (Cursor).

Key principles:

• Trigger-rich description — the description field is what the agent matches against your request. Include synonyms and related phrases.
• Stepwise, not essay — agents follow numbered steps. Don't write paragraphs.
• Progressive disclosure — put the core steps in SKILL.md. Put reference material in separate files the skill links to.
• One skill, one job — a skill that does "code review and deployment and testing" is three skills. Split them.

Matt Pocock's skill-writing skill (if you have it): run it to get a template and guidance for writing a new skill.

To create a new skill:

~/.agents/skills/<name>/
├── SKILL.md          # Required
├── agents/           # Optional
│   └── openai.yaml
└── <references>/     # Optional

Then symlink it (Claude Code):

ln -s ~/.agents/skills/<name> ~/.claude/skills/<name>

For Cursor, add a rule file in .cursor/rules/ that references the skill or inlines its content.

Run the Planning Pipeline #

The planning pipeline is the sequence that turns a vague idea into executable tickets.

Grill the Idea (/grilling) #

Before writing anything down, stress-test the plan. The grilling skill interviews you relentlessly about every aspect of the idea, walking down each branch of the decision tree. It asks one question at a time, provides a recommended answer, and waits for your feedback.

When to grill: Any time the problem is non-trivial, the requirements are fuzzy, or you're about to commit to a direction you haven't fully thought through.

Capture the Spec (/to-prd or /to-spec) #

Once the idea is clear, run to-prd or to-spec to write a formal document. It synthesises what you already discussed — no interview. The output includes: problem statement, user stories, implementation decisions, testing decisions, and out of scope.

to-prd and to-spec produce the same template. Use whichever name your team prefers.

Slice into Tickets (/to-tickets) #

Break the spec into tracer-bullet vertical slices. Each ticket:

• Cuts a narrow but complete path through every layer (schema, API, UI, tests)
• Is demoable or verifiable on its own
• Fits in a single fresh context window
• Declares its blocking edges

Implement (/implement) #

Execute the tickets one at a time. Uses /tdd where possible, runs typechecking and tests regularly, runs /code-review before committing, and commits to the current branch.

Use the Two-Tier Model Strategy #

Different models excel at different parts of the workflow. Use the right model for the right job.

When to use frontier models: Grilling, writing specs, slicing tickets, architecture design, code review, designing test seams, debugging hard problems.

When to use cheap / local models: Implementing tickets with clear AC, writing boilerplate, running tests, simple refactors.

The Combo Loop #

The most efficient pattern uses both tiers together:

• In Claude Code: Use Claude Code (Plan) mode for planning, then switch to regular mode for execution.
• In Cursor: Use the model picker in the Composer — select Opus/Fable for planning, switch to a cheaper model for execution.

**Why this works:** The expensive model does the thinking once. The cheap model does the typing many times. The expensive model catches mistakes before they ship.

Manage Tokens #

Token usage is the main cost driver when using coding agents. Two tools help reduce it:

caveman (caveman.so) #

A tool that reduces token usage by stripping unnecessary context from prompts and conversations. Install: See caveman.so.

rtk — Rust Token Killer (rtk-ai.app) #

A CLI tool that compresses command outputs before they reach the AI context window. rtk init --global installs a PreToolUse hook. Results: 89% average noise removal, 60–90% token savings, 3x longer sessions. Open source (Apache 2.0), written in Rust.

curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
rtk init --global

Token Hygiene Habits #

• One ticket per session — don't load multiple tickets into one context window.
• Don't paste entire files — paste only the relevant function or section.
• Use instruction files — CLAUDE.md and skills keep the agent from re-learning conventions.
• Fresh context windows — if a session gets long, commit and start a new one.
• Prefer to-tickets over long conversations — a well-scoped ticket is cheaper than a sprawling chat.

Pick a Knowledge-Graph Strategy #

Knowledge graphs help you understand unfamiliar codebases faster, build context without re-reading files, and reduce token usage during planning. Neither you, nor an LLM need to get lost or establish context from scratch every time you work on a ticket.

Approach A: understand-anything #

The /understand skill suite analyses a codebase and produces an interactive knowledge graph that can be explored in a dashboard, used for Q&A, onboarding, diffing, and domain exploration.

To use it:

1. Run /understand-quick <path> to build a lightweight graph
2. Or run /understand <path> for a full analysis
3. Then use /understand-dashboard to explore the graph
4. Use /understand-chat for Q&A over the codebase
5. Use /understand-onboard <ticket-link> to generate onboarding summaries
6. Use /understand-diff <a> <b> to compare two states
7. Use /understand-domain to explore the business domain

Visit understand-anything.com to learn more. A demo is available on the website.

Pros: Easier context building, less re-reading code, reduced token usage when planning. You get an interactive dashboard to explore the codebase and ask questions about it, which is great for onboarding and learning.

Cons There is an upfront cost. It isn't money, but tokens and time. You have to wait for the analysis to complete before you can start using the knowledge graph. It's worth it for large codebases, but it can be overkill for small ones. If a codebase changes frequently, you will have to update the knowledge graph regularly.

Approach B: graphify + Obsidian #

Use graphify (or similar tools) to export codebase structure as markdown files, then load them into Obsidian for a browsable, linked-graph vault. Visual exploration, local-first, works offline.

**Key insight:** A knowledge graph lets you navigate a codebase by *concept* rather than by *file path*.

Always TDD #

Test-driven development is the safety net that makes cheap-model execution viable.

Key rules: Red before green. One slice at a time. Test at pre-agreed seams. Test behaviour, not implementation.

Anti-patterns: Implementation-coupled tests, tautological tests (expect(add(a, b)).toBe(a + b)), horizontal slicing.

**Why TDD matters for LLM development:** A well-scoped ticket + a failing test = the agent has a clear target. It can use a cheap model, iterate quickly, and you can review the diff with confidence.

Deepen the Architecture When Needed #

When the code starts resisting change — when adding a feature requires touching ten files, when tests are brittle, when the same concept is scattered across modules — run the improve-codebase-architecture skill.

When to run it: Adding a significant feature that's painful, a module's interface is as complex as its implementation, onboarding new team members, or tests are consistently brittle.

**Don't run it** for small changes, for code that's working fine, or when you're under time pressure. Architecture work is an investment — make it when the return is clear.

The Daily Loop #

Here's how it all fits together in a typical day:

When starting something new:

When the codebase feels painful: