Buildmate를 실제로 사용하는 방법 (실용 가이드)

Source: Dev.to

설치했는데, 이제 뭐하지?

아마도 Buildmate에 대한 내 첫 번째 글을 읽었거나, 그냥 GitHub 저장소를 우연히 발견하고 “멋지다, 한번 써볼까” 라고 생각했을 수도 있겠죠. 어쨌든 설치는 끝났지만, 이제 터미널 앞에 서서 “…이걸 가지고 실제로 뭘 해야 하지?” 라고 고민하고 있을 겁니다.

문서는 훌륭하지만, 때로는 누군가가 실제로 도구를 어떻게 사용하는지 보여주길 원하죠. 바로 그 내용입니다. 실제 워크플로우. 실제 명령어. 내가 매일 하는 일들.

갑시다.

빠른 설정 (놓쳤다면)

이미 하셨다면 건너뛰세요. 아직이라면:

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

그 다음 프로젝트를 부트스트랩하세요:

# 스택 선택
buildmate rails /path/to/my-app
buildmate nextjs /path/to/my-app --ui=tailwind
buildmate rails+nextjs /path/to/my-app

# 혹은 프리셋 사용
buildmate --profile saas /path/to/my-app

어떤 스택이 있는지 모르겠나요? 다음으로 확인하세요:

buildmate --list           # 모든 스택
buildmate --profiles       # 프리셋 조합
buildmate --options nextjs # 스택 옵션

이후 .claude/ 폴더에 에이전트 관련 파일들이 모두 생성됩니다. 이제 준비가 끝났습니다.

Source: …

첫 번째 /pm 명령

/pm 은 메인 명령입니다. PM 은 Project Manager 를 의미합니다. 전체 워크플로우—계획, 구축, 테스트, 검토—를 시작합니다.

1. 프로젝트를 열고 claude 를 실행합니다.
2. 다음을 입력합니다:

/pm Build a user profile page with avatar, bio, and edit functionality

Phase 1 – Planning (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, here's the plan:
    [shows feature file with all the details]

    Ready to build?

You: yep go

Phases 2‑5 – Automatic

여기부터는 에이전트들이 작업을 이어갑니다:

[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+)

이제 테스트, 리뷰, 검증까지 포함된 작동하는 프로필 페이지가 준비되었습니다.

Note: 마법처럼 보이지만, 순서대로 작동하는 특화된 에이전트들의 집합일 뿐입니다. 백엔드 개발자는 백엔드를, 프론트엔드 개발자는 UI를, 테스터는 테스트를 작성합니다.

에이전트 (누가 무엇을 하나?)

에이전트는 .claude/agents/ 디렉터리에 마크다운 파일로 존재합니다. 자유롭게 읽거나 편집하세요—추후에 자세히 다루겠습니다.

실제로 사용할 명령어

/pm "task"

가장 중요한 명령어입니다. 전체 워크플로를 시작합니다.

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

새로운 기능, 큰 수정, 새로운 페이지 등 실질적인 작업에 사용하세요.

/verify

코드를 실행해 테스트합니다. 비교적 새 기능이며 저는 항상 사용합니다.

/verify                              # test last changes
/verify --component Navbar           # test a specific component
/verify --endpoint POST /api/users   # test a specific endpoint
/verify --page /dashboard            # test a whole page

무언가 실패하면 시스템이 자동으로 (최대 세 번) 수정하려 시도합니다.

/new-model and /new-component

빠른 스캐폴딩으로 해당 객체와 테스트 및 보일러플레이트를 함께 생성합니다.

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

프로젝트 규칙을 따르며 수작업을 크게 줄여줍니다.

/parallel

독립적인 작업이 있나요? 동시에 실행하세요.

/parallel "Add user avatars" "Add product images" "Add company logos"

개요

별도의 Git 워크트리를 사용하고, 각각에서 에이전트를 실행한 뒤 완료되면 병합합니다. 비슷한 작업이 여러 개 있을 때 유용합니다.

/security

Security audit – 배포하기 전에 실행해 주세요.

/security

인젝션, 인증 문제, XSS, CSRF 및 기타 OWASP 관련 사항을 검사합니다.

/eval

전체 워크플로우 없이 빠른 점수를 원하시나요?

/eval

점수를 반환합니다 – 자신의 작업을 확인하는 데 유용합니다.

/test 및 /review

필요한 것만 실행하세요:

/test          # just run tests
/review        # just review current changes

Git 워크플로우 (The /branch → /ship Flow)

브랜치를 수동으로 만들고, 커밋 메시지를 작성하고, 푸시하고, 오후 5시쯤 머리가 뜨거워진 상태에서 PR 설명을 초안하는 대신, 간단히:

/branch user-auth          # creates feature/user-auth
# … do your work or use /pm …
/ship                      # commits, pushes, creates PR

• 변경 사항으로부터 커밋 메시지를 자동 생성합니다.
• PR 설명을 대신 작성합니다.
• 배포 전 품질 게이트를 실행합니다.

더 많은 예시

/branch login-fix --type fix          # creates fix/login-fix
/branch user-auth --issue 42          # links to GitHub issue #42
/sync                                 # rebase on main if you’re behind
/ship --draft                         # create PR as draft

동기화

/sync                    # rebase on main
/sync --merge            # merge instead of rebase
/sync --base develop     # sync with develop branch

배포

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

“아, 푸시를 깜빡했어.” 라는 상황은 이제 없습니다. PR 템플릿을 보며 어떤 부분을 바꿨는지 기억하려 애쓰는 일도 없습니다—명령어가 모든 것을 처리해 줍니다.

설정 맞춤화

에이전트 편집

에이전트는 일반 마크다운 파일입니다. 워크플로에 맞게 편집하세요.

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

파일을 열어 지시사항, 패턴, 해야 할 일과 하지 말아야 할 일을 확인하세요. 원하는 대로 변경하세요.

예시: 백엔드 개발자가 항상 특정 gem을 사용하도록 강제합니다.

# backend-developer.md (excerpt)

선호하는 젬

• my-special-gem (>= 2.0)

각 에이전트의 동작을 팀의 관례에 맞게 자유롭게 조정하세요.

규칙

• 페이지네이션에는 Pagy를 항상 사용하세요 (Kaminari는 사용 금지)
• 권한 부여에는 Pundit를 항상 사용하세요
• …

패턴 추가

항상 따르는 코딩 패턴이 있나요? .claude/patterns/에 추가하세요.
이들은 에이전트가 읽는 참고 문서이며, 예를 들어 “서비스 구조화 방법”이나 “우리 API 응답 형식”과 같은 내용이 될 수 있습니다.

품질 게이트 변경

스택 설정에서 실행되는 명령을 변경할 수 있습니다:

quality_gates:
  lint:
    command: bundle exec rubocop
    fix_command: bundle exec rubocop -A
  tests:
    command: bundle exec rspec

더 추가하거나, 일부를 제거하거나, 명령을 변경하세요—프로젝트에 맞게 자유롭게 적용하면 됩니다.

실제로 사용하는 워크플로우

새로운 기능 구축

이 흐름은 내 작업의 약 80 %에 해당합니다:

1. /pm Build [feature description]
2. 요구 사항에 대한 몇 가지 질문에 답변
3. 계획 승인
4. 커피 마시러 가기
5. 돌아와서 – 완료
6. 작은 부분을 수동으로 약간 수정
7. 커밋하고 푸시

대부분의 기능은 이제 반나절이 아니라 10‑15 분이면 끝납니다.

버그 수정

1. /pm Fix [describe the bug and where it is]
2. 에이전트가 코드를 읽고 문제를 찾음
3. 수정함
4. 다시 발생하지 않도록 테스트 작성
5. 완료

작은 버그는 직접 고치는 것이 더 빠를 때가 있지만, 복잡한 경우에는 에이전트에게 맡깁니다.

기존 코드에 추가

1. /pm Add [thing] to [existing feature]
2. 에이전트가 먼저 기존 코드를 읽음
3. 이미 존재하는 패턴을 따름
4. 같은 스타일로 새로운 항목을 추가

에이전트가 코드를 읽고 스타일을 맞추기 때문에 “새 코드는 기존 코드와 완전히 다르다”는 상황이 발생하지 않습니다.

빠른 스캐폴딩 데이

새 프로젝트를 설정할 때 한 번에 여러 명령을 실행합니다:

/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
...

몇 분 안에 모든 것이 스캐폴드됩니다(테스트 포함).

일반적인 문제 (및 해결 방법)

실제로 이 도구를 사용할 때 팁

• 프롬프트를 구체적으로 작성하세요. “Build a login page”(로그인 페이지 만들기)는 괜찮지만; “Build a login page with email/password, remember‑me checkbox, forgot‑password link, and redirect to dashboard after login”(이메일/비밀번호, 기억하기 체크박스, 비밀번호 찾기 링크, 로그인 후 대시보드로 리다이렉트되는 로그인 페이지 만들기)는 더 좋습니다.
• 계획 질문에 답하세요. 그냥 “뭐든지”라고 하지 마세요. 더 많은 맥락 → 더 좋은 결과.
• /verify를 자주 사용하세요. 눈치채기 전에 어리석은 실수를 잡아줍니다.
• 피처 파일을 읽으세요. .claude/context/features/에 위치하며, 무엇을 만들었고 왜 만들었는지 기억하는 데 유용합니다.
• 에이전트를 편집하세요. 진지하게—당신만의 것으로 만드세요. 당신의 패턴, 규칙, 선호도를 추가하세요.
• 신뢰하되 검증하세요. 코드는 보통 좋지만, 배포 전에 항상 한 번 빠르게 살펴보세요.
• git 흐름을 사용하세요. /branch → 작업 수행 → /ship. 오후 5시에 수동 PR 설명을 작성할 필요가 없습니다.

다음 단계

저는 웹사이트‑클론 도구를 개발 중입니다: 어떤 사이트든 가리키면 UI 라이브러리를 사용해 여러분만의 버전을 생성합니다. 이는 별도의 글이 될 것입니다.

우선, 이걸 직접 시도해 보세요. 깨뜨려 보고, 고쳐 보세요. 무엇이 작동하고 무엇이 안 되는지 알려 주세요.

GitHub:

이것이 유용했나요?

시간을 절약했다면, 저에게 커피 한 잔 사주시겠어요?

☕ Buy Me A Coffee

이제 멋진 것을 만들어 보세요.

— Vadim