DEV Community

Cover image for How to Actually Use Buildmate (The Practical Guide)
Vadim Karnopelev
Vadim Karnopelev

Posted on

How to Actually Use Buildmate (The Practical Guide)

#ai #programming #tutorial #productivity

because "just read the docs" isn't helpful and we both know it

Hit the paywall? Read this article for free here

So You Installed It, Now What?

Ok so maybe you read my first post about Buildmate. Or maybe you just found the GitHub and thought "cool I'll try it." Either way - you got it installed but now you're staring at your terminal like "...what do I actually do with this thing?"

Yeah I get it. Docs are great and all but sometimes you just want someone to show you how they actually use the thing. So thats what this is. Real workflows. Real commands. Stuff I actually do every day.

Lets go.

Quick Setup (In Case You Skipped It)

If you already did this skip ahead. If not:

git clone https://github.com/vadim7j7/buildmate.git
cd buildmate
python3 -m venv .venv && .venv/bin/pip install -e .
Enter fullscreen mode Exit fullscreen mode

Then bootstrap your project:

# Pick your stack
buildmate rails /path/to/my-app
buildmate nextjs /path/to/my-app --ui=tailwind
buildmate rails+nextjs /path/to/my-app

# Or just use a preset
buildmate --profile saas /path/to/my-app
Enter fullscreen mode Exit fullscreen mode

Not sure what stacks are available? Check with:

buildmate --list           # all stacks
buildmate --profiles       # preset combos
buildmate --options nextjs # options for a stack
Enter fullscreen mode Exit fullscreen mode

After this you got a .claude/ folder with all the agent stuff. Thats it. Your ready.

Your First /pm Command

Ok so /pm is the main thing. PM stands for Project Manager. Its the command that kicks off the whole workflow - planning, building, testing, reviewing, everything.

Lets try it. Open your project and run claude, then type:

/pm Build a user profile page with avatar, bio, and edit functionality
Enter fullscreen mode Exit fullscreen mode

Heres what happens:

Phase 1 - Planning (this part is interactive)

PM: Ok so for user profile, I'm thinking:

    Requirements:
    - Profile page showing avatar, name, bio
    - Edit mode to update info
    - Avatar upload (or URL?)
    - Save/cancel buttons

    Questions:
    - Should avatar be file upload or just URL input?
    - Where does this page live? /profile? /settings?
    - Need to create User model or exists already?

You: URL is fine for now. /profile route. User model exists.

PM: Cool, heres the plan:
    [shows feature file with all the details]

    Ready to build?

You: yep go
Enter fullscreen mode Exit fullscreen mode

Phases 2-5 (automatic from here)

Now it just runs. You dont do anything.

[Phase 2: Implementation]
→ Spawning backend-developer...
→ Creating ProfileController
→ Adding routes
→ Spawning frontend-developer...
→ Creating ProfilePage component
→ Creating EditProfileForm component

[Phase 3: Testing]
→ Spawning testers...
→ Writing controller specs
→ Writing component tests
→ Running quality gates...
→ Grind agent fixing 2 lint errors...

[Phase 4: Review]
→ Spawning reviewers...
→ Backend review: APPROVED
→ Frontend review: APPROVED

[Phase 5: Verification]
→ Starting dev server...
→ Testing /profile route...
→ Component renders ✓
→ Form submits ✓

Done! Score: 0.89 (B+)
Enter fullscreen mode Exit fullscreen mode

And now you have a working profile page. With tests. Reviewed. Verified.

I know it sounds like magic but its not really. Its just agents doing their specific jobs in order. Backend dev writes backend. Frontend dev writes frontend. Tester writes tests. Each one is focused on one thing.

The Agents (Who Does What)

Quick reference cause I always forget:

Agent What It Does When It Runs
PM/Orchestrator Plans the work, coordinates everyone First, stays in control
Backend Developer Writes Rails/FastAPI code Phase 2
Frontend Developer Writes React/Next.js code Phase 2
Backend Tester Writes backend tests Phase 3
Frontend Tester Writes frontend tests Phase 3
Grind Runs linters in loop, fixes errors Phase 3
Verifier Actually runs the code to test it Phase 3-4
Reviewers Code review Phase 4
Eval Scores the code Phase 5
Security Auditor Checks for vulnerabilities When you ask

They live in .claude/agents/ as markdown files. You can read them if your curious. Or edit them - more on that later.

Commands You'll Actually Use

/pm "task"

The big one. Full workflow.

/pm Add pagination to the products list
/pm Fix the login bug where sessions expire too fast
/pm Build checkout flow with Stripe integration
Enter fullscreen mode Exit fullscreen mode

Use this for anything substantial. Features, big fixes, new pages.

/verify

Tests your code by actually running it. This ones newer and honestly I use it all the time now.

/verify                              # test last changes
/verify --component Navbar           # test specific component
/verify --endpoint POST /api/users   # test specific endpoint
/verify --page /dashboard            # test whole page
Enter fullscreen mode Exit fullscreen mode

If something fails it tries to fix it automatically. Up to 3 times.

/new-model and /new-component

Quick scaffolding. Creates the thing plus tests plus all the boilerplate.

/new-model Product name:string price:decimal active:boolean
/new-component ProductCard
/new-component forms/CheckoutForm
Enter fullscreen mode Exit fullscreen mode

Way faster than doing it manually. Follows your project conventions too.

/parallel

Got independent tasks? Run them at the same time.

/parallel "Add user avatars" "Add product images" "Add company logos"
Enter fullscreen mode Exit fullscreen mode

Creates separate git worktrees, runs agents in each, merges when done. I use this when I got a bunch of similar things to do.

/security

Security audit. Run it before you deploy pls.

/security
Enter fullscreen mode Exit fullscreen mode

Checks for injection, auth issues, XSS, CSRF, all that OWASP stuff.

/eval

Just want a score without the whole workflow?

/eval
Enter fullscreen mode Exit fullscreen mode

Gives you the grade. Good for checking your own work.

/test and /review

Sometimes you just want one thing:

/test          # just run tests
/review        # just review current changes
Enter fullscreen mode Exit fullscreen mode

Git Workflow (The /branch → /ship Flow)

Ok so this one is newer and I use it all the time now.

Instead of manually creating branches, writing commit messages, pushing, writing PR descriptions at 5pm when your brain is fried... just:

/branch user-auth                    # creates feature/user-auth
# ... do your work or use /pm ...
/ship                                # commits, pushes, creates PR
Enter fullscreen mode Exit fullscreen mode

Thats it. It auto-generates commit messages from your changes. Writes the PR description for you. Even runs quality gates before shipping.

More examples:

/branch login-fix --type fix         # creates fix/login-fix
/branch user-auth --issue 42         # links to github issue #42
/sync                                # rebase on main if youre behind
/ship --draft                        # create PR as draft
Enter fullscreen mode Exit fullscreen mode

The /sync one is useful when main has moved ahead and you need to catch up. It handles the rebase (or merge if you prefer) and force-pushes for you.

/sync                    # rebase on main
/sync --merge            # merge instead of rebase
/sync --base develop     # sync with develop branch
Enter fullscreen mode Exit fullscreen mode

And /ship does everything at once:

/ship                    # commit + push + create PR
/ship --draft            # same but draft PR
/ship --no-pr            # just commit and push, no PR
Enter fullscreen mode Exit fullscreen mode

No more "oh wait I forgot to push." No more staring at the PR template trying to remember what you changed. It just does it.

Customizing Your Setup

Editing Agents

The agents are just markdown files. You can edit them.

.claude/agents/
├── orchestrator.md      # the PM brain
├── backend-developer.md # Rails/FastAPI dev
├── frontend-developer.md
├── grind.md
└── ...
Enter fullscreen mode Exit fullscreen mode

Open one up. Youll see instructions, patterns, do's and donts. Change whatever you want.

For example maybe you want the backend dev to always use a specific gem:

## Rules

- Always use Pagy for pagination (not Kaminari)
- Always use Pundit for authorization
- ...
Enter fullscreen mode Exit fullscreen mode

Just add it to the file. Next time it runs itll follow your rules.

Adding Patterns

Got coding patterns you always follow? Add them to .claude/patterns/.

These are reference docs the agents read. Stuff like "how we structure services" or "our API response format."

Changing Quality Gates

In the stack config you can change what commands run:

quality_gates:
  lint:
    command: bundle exec rubocop
    fix_command: bundle exec rubocop -A
  tests:
    command: bundle exec rspec
Enter fullscreen mode Exit fullscreen mode

Add more, remove some, change commands. Whatever works for your project.

Real Workflows I Actually Use

Building a New Feature

This is like 80% of what I do:

1. /pm Build [feature description]
2. Answer a few questions about requirements
3. Approve the plan
4. Go get coffee
5. Come back, its done
6. Maybe tweak something small manually
7. Commit and push
Enter fullscreen mode Exit fullscreen mode

Thats it. Most features take 10-15 minutes now instead of half a day.

Fixing a Bug 

1. /pm Fix [describe the bug and where it is]
2. Agent reads the code, finds the issue
3. Fixes it
4. Writes a test so it doesnt happen again
5. Done
Enter fullscreen mode Exit fullscreen mode

For small bugs I sometimes just do it myself cause its faster. But for anything tricky I let the agent figure it out.

Adding to Existing Code 

1. /pm Add [thing] to [existing feature]
2. Agent reads the existing code first
3. Follows the patterns already there
4. Adds the new thing in the same style
Enter fullscreen mode Exit fullscreen mode

This is where it really shines tbh. It actually reads your code and matches the style. No more "this new code looks totally different from everything else."

Quick Scaffolding Day

When I'm setting up a new project I'll just rapid fire:

/new-model User email:string name:string
/new-model Product title:string price:decimal
/new-model Order user:references total:decimal
/new-component Navbar
/new-component Footer
/new-component ProductCard
...
Enter fullscreen mode Exit fullscreen mode

Boom. All the basics in like 5 minutes. With tests.

Common Issues (And How to Fix Them)

"Its stuck in a loop"

The grind agent will try 10 times then give up. If its not converging theres probably something weird going on. Read the error, might need manual fix.

"Agent didnt follow my style"

Edit the agent file in .claude/agents/. Add specific rules about your style. Be explicit - "always use X, never use Y."

"Tests keep failing"

Check if your test setup is correct. Sometimes the agent writes good tests but the test environment isnt configured right. Run the tests manually to see whats up.

"It made too many files"

Yeah it can get enthusiastic sometimes. You can tell it in the initial prompt: "keep it simple, minimal files."

"The code works but I dont like how its structured"

Use /review to get feedback, or just refactor yourself. The agents are good but theyre not perfect. Your judgment still matters.

Tips From Actually Using This Thing

  1. Be specific in your prompts. "Build a login page" is ok. "Build a login page with email/password, remember me checkbox, forgot password link, and redirect to dashboard after" is better.

  2. Answer the planning questions. Dont just say "whatever." The more context you give, the better the output.

  3. Use /verify often. Catches dumb mistakes before you even see them.

  4. Read the feature files. They live in .claude/context/features/. Good for remembering what was built and why.

  5. Edit the agents. Seriously. Make them yours. Add your patterns, your rules, your preferences.

  6. Trust but verify. The code is usually good but always do a quick look before shipping.

  7. Use the git flow. /branch → do work → /ship. No more manual PR descriptions at 5pm.

Whats Next

Working on website cloning - point it at any site and itll generate your own version using your UI library. Thats gonna be a whole other post tho.

For now, go try this stuff. Break things. Fix things. Let me know what works and what doesnt.

GitHub: github.com/vadim7j7/buildmate

Found This Useful?

If this saved you some time maybe buy me a coffee?

☕ Buy Me A Coffee

Now go build something cool.

- Vadim

Top comments (0)