아이디어 검증부터 구현, 리뷰, 학습 축적까지 연결하기

Claude Code를 처음 쓸 때는 대부분 이렇게 시작했다.

이 기능 만들어줘.
이 에러 고쳐줘.
이 컴포넌트 리팩토링해줘.

이것만으로도 충분히 편했다.

파일을 읽고, 코드를 고치고, 테스트까지 돌려주는 경험은 확실히 기존 개발 방식과 달랐다.

그런데 프로젝트가 조금만 커지면 다른 문제가 생겼다.

코드는 빨리 나오는데,
정작 “이걸 지금 만드는 게 맞나?”라는 질문은 자꾸 뒤로 밀렸다.

기능을 만들고 나서야 범위가 너무 컸다는 걸 깨닫거나,
이미 비슷한 패턴이 코드베이스에 있었는데 새로 구현하거나,
한 번 고쳤던 문제를 몇 주 뒤에 다시 디버깅하는 일이 생겼다.

그래서 요즘은 Claude Code를 단순한 코딩 보조 도구로 보기보다,
하나의 개발 워크플로우로 다루려고 하고 있다.

나는 GSD까지 포함한 풀세트 워크플로우를 쓴 것은 아니다.

대신 gstack으로 “무엇을 만들지”를 먼저 검증하고,
Superpowers로 “어떻게 구현할지”를 잡은 뒤,
마지막에 Compound Engineering식 피드백 루프를 수동으로 붙였다.

핵심은 이거였다.

코딩 자체보다,
코딩 전후의 과정에서 더 큰 차이가 난다.

---

이 워크플로우에서 각 도구가 맡은 역할

내가 느낀 역할은 대략 이렇다.

구분	역할	핵심 질문
gstack	전략 수립과 검증	무엇을 왜 만들 것인가?
Superpowers	구현 방식과 품질 관리	어떻게 안정적으로 만들 것인가?
Compound Engineering식 피드백 루프	학습 축적과 재사용	이번 작업에서 얻은 판단, 패턴, 해결책을 다음 작업에 어떻게 반영할 것인가?

여기서 중요한 점은 Compound Engineering을 특정 명령어 묶음처럼 쓴 게 아니라는 점이다.

원문에서 말하는 Compound Engineering의 핵심은 단순히 “문서를 남긴다”가 아니다.
각 개발 사이클이 끝날 때마다, 이번 작업에서 생긴 판단과 해결책을 다음 작업의 입력값으로 바꾸는 것이다.

즉, 기능 하나를 만들고 끝내는 것이 아니라:

이번 작업에서 무엇을 배웠는가?
이 문제는 다음에 어떻게 더 빨리 피하거나 해결할 수 있는가?
이 내용을 AI가 다음 작업에서 자동으로 참고할 수 있는가?

를 남기는 과정에 가깝다.

내가 사용한 방식은 Every의 Compound Engineering 플러그인을 그대로 따라간 것은 아니었다.
대신 리뷰 이후에 나온 실수, 해결책, 반복 가능한 패턴을 문서화하고, 다음 Claude Code 작업 전에 다시 참조하게 하는 방식으로 수동 적용했다.

구조는 이렇게 나뉜다.

gstack
→ 만들기 전에 방향을 검증한다.

Superpowers
→ 구현 과정에서 품질 기준을 잡는다.

Compound Engineering식 피드백 루프
→ 구현과 리뷰에서 나온 판단, 실수, 해결책을 다음 작업의 컨텍스트로 남긴다.

---

전체 흐름 개요

전체 사이클은 5단계로 구성했다.

Phase 1: 전략 수립 ─────────────────── gstack
  95% 확신 프롬프트
  /office-hours
  /plan-ceo-review
  /plan-eng-review

        │

Phase 2: 구현 범위 정리 ───────────── 사용자 + Claude
  요구사항 정리
  제외 범위 정의
  성공 기준 정리
  기존 코드베이스 맥락 확인

        │

Phase 3: 구현 ─────────────────────── Superpowers
  테스트 기준 확인
  계획 기반 구현
  필요한 경우 TDD / 디버깅 / 병렬 에이전트 활용

        │

Phase 4: 검증 ─────────────────────── Superpowers + gstack
  코드 리뷰
  품질 검토
  /qa
  실제 사용자 흐름 확인

        │

Phase 5: 학습 축적 ─────────────────── Compound Engineering식 피드백 루프
  리뷰 지적사항 확인
  문제와 원인 정리
  재사용 가능한 해결책 문서화
  AGENTS.md 또는 CLAUDE.md에 규칙 반영
  다음 작업 전 참조

GSD를 쓰는 워크플로우라면 중간에 .planning/, milestone, phase plan 같은 구조가 들어갈 수 있다.

하지만 나는 그 정도로 프로젝트 관리 체계를 세우지는 않았다.

대신 “계획과 상태 관리”보다는,
AI가 반복해서 놓치는 맥락을 줄이는 것에 더 집중했다.

---

Phase 1. 전략 수립 — gstack

코드를 한 줄도 작성하기 전에 먼저 무엇을 왜 만들지 정리했다.

가장 먼저 쓴 프롬프트는 이거다.

저는 이 프로젝트를 시작하려고 합니다:

[프로젝트를 1~2문장으로 설명]

제가 실제로 원하는 것이 무엇인지, 제가 생각하는 것이 아니라,
95% 확신을 가질 때까지 저에게 질문하세요.

제 가정을 검증하세요.
제가 고려하지 않은 예외적인 경우에 대해 질문하세요.

이 프롬프트의 좋은 점은 바로 답을 받는 게 아니라,
Claude가 나에게 질문하게 만든다는 점이다.

예전에는 내가 애매하게 말해도 Claude가 알아서 그럴듯한 계획을 만들어줬다.
문제는 그 계획이 그럴듯할 뿐, 꼭 맞는 계획은 아닐 때가 많았다는 것이다.

예를 들어 “관리자 대시보드 개선”이라고만 말하면 너무 넓다.

그런데 Claude가 계속 질문하면 범위가 좁아진다.

관리자 대시보드 개선
→ 최근 30일 매출 추이를 빠르게 확인하는 화면
→ 상품별 매출 상위 10개 표시
→ CSV 다운로드는 이번 범위에서 제외
→ 모바일 최적화도 다음 버전으로 미룸

그 다음에는 gstack의 /office-hours를 사용했다.

이 단계는 약간 아이디어 상담에 가깝다.

이 기능은 누구를 위한 건가요?
지금 사용자는 이 문제를 어떻게 해결하고 있나요?
이 기능이 없으면 정말 불편한가요?
MVP로 줄이면 어디까지인가요?

이 과정에서 “하고 싶은 기능”과 “지금 필요한 기능”이 분리된다.

혼자 개발하다 보면

이거 있으면 멋질 것 같은데?

라는 이유만으로 기능을 추가하기 쉽다.

그래서 /plan-ceo-review와 /plan-eng-review도 같이 사용했다.

/plan-ceo-review
→ 이걸 만들 가치가 있는가?
→ 실제 문제를 해결하는가?
→ 지금 우선순위가 맞는가?

/plan-eng-review
→ 현재 구조와 잘 맞는가?
→ 데이터 흐름이 명확한가?
→ 나중에 확장하기 어려워지지 않는가?
→ 인증, 권한, 성능 문제가 생기지 않는가?

이 단계는 코딩 속도를 늦추는 것처럼 보이지만,
실제로는 나중에 되돌릴 일을 줄여준다.

---

Phase 2. 구현 범위 정리 — 요구사항을 사양으로 바꾸기

전략이 어느 정도 잡히면 바로 구현으로 들어가지 않았다.

그 전에 요구사항과 접근 방식을 한 번 더 정리했다.

이 단계는 막연한 아이디어를 구현 가능한 사양으로 바꾸는 과정에 가깝다.

예를 들어 처음에는 이렇게 말할 수 있다.

게시글 추천 기능을 만들고 싶다.

하지만 이 상태로 바로 구현하면 범위가 쉽게 커진다.

추천 기준은 무엇인지,
어떤 데이터를 사용할지,
캐시는 필요한지,
추천 결과가 없을 때는 어떻게 처리할지,
이번 버전에서 하지 않을 것은 무엇인지가 아직 정리되지 않았기 때문이다.

그래서 구현 전에 이런 식으로 정리했다.

목표:
- 사용자가 관심 있을 만한 게시글을 홈 피드에 보여준다.

이번 범위:
- 최근 조회/좋아요 기반 추천
- 추천 결과 Redis 캐싱
- 추천 결과가 없으면 최신 게시글 fallback

제외 범위:
- 팔로우 기반 추천
- 별도 ML 모델 학습
- 개인화 알림

성공 기준:
- 홈 피드 API 평균 응답 시간 200ms 이하
- 추천 결과 최소 10개 반환
- 캐시 미스 시에도 정상 fallback

여기서 제일 중요했던 건 “이번에 하지 않을 것”을 적어두는 일이었다.

기능은 그냥 두면 계속 불어난다.
그래서 제외 범위를 먼저 적어두는 것만으로도 구현 중간의 흔들림이 줄었다.

또 하나 신경 쓴 건 기존 코드베이스 맥락이었다.

기존 폴더 구조
비슷한 기능 구현 방식
이미 있는 유틸 함수
기존 API 요청 방식
테스트 패턴
최근 리뷰에서 지적된 내용

Claude가 일반적인 모범 사례만 보고 코드를 짜면,
기존 프로젝트와 어울리지 않는 새 패턴을 만들 때가 있다.

예를 들어 프로젝트에서 이미 이런 규칙을 쓰고 있을 수 있다.

API 요청은 customFetcher를 사용한다.
인증 에러는 BFF Route Handler에서 처리한다.
React Query queryKey는 feature 단위로 관리한다.
폼 검증은 zod 기반으로 통일한다.

이 맥락을 놓치면 비슷한 기능을 전혀 다른 방식으로 구현하게 된다.

그래서 구현 전에 기존 코드 흐름과 프로젝트 규칙을 먼저 확인하게 했다.

---

Phase 3. 구현 — Superpowers

구현 단계에서는 Superpowers 쪽 흐름을 참고했다.

내가 Superpowers에서 좋게 본 부분은 “바로 코드부터 쓰지 않게 만드는 점”이었다.

예를 들어 새 기능을 만들 때는 먼저 이렇게 정리한다.

무엇을 구현할 것인가?
성공 기준은 무엇인가?
어떤 테스트가 필요할까?
기존 패턴과 충돌하지 않는가?

그리고 필요한 경우 TDD 방식으로 진행했다.

Step 1. 실패하는 테스트 작성
Step 2. 테스트를 통과하는 최소 구현
Step 3. 리팩토링
Step 4. 회귀 테스트

버그를 고칠 때도 바로 수정하지 않고, 먼저 재현 조건과 가설을 정리했다.

문제:
- 특정 상황에서 추천 피드가 빈 배열로 내려온다.

관찰:
- 로그인 직후 첫 요청에서만 발생한다.
- 새로고침하면 정상 동작한다.

가설:
1. userId가 초기화되기 전에 요청이 나간다.
2. 캐시 키가 잘못 만들어진다.
3. 서버 fallback 로직이 비어 있다.

검증:
- 요청 시점 로그 확인
- queryKey 확인
- 서버 응답 확인

이렇게 하면 감으로 코드를 고치는 일을 줄일 수 있다.

이 단계에서 Superpowers는 “무엇을 만들지”를 결정하는 도구라기보다,
구현 과정이 너무 즉흥적으로 흐르지 않게 잡아주는 역할에 가까웠다.

---

Phase 4. 검증 — 리뷰와 QA

구현이 끝났다고 바로 끝내지는 않았다.

먼저 코드 리뷰를 거쳤다.

여기서 중요하게 본 건 만든 쪽과 검사하는 쪽을 분리하는 것이었다.

코드를 만든 AI에게 다시 “괜찮지?”라고 물으면,
생각보다 관대하게 넘어갈 때가 있다.

그래서 리뷰 관점을 나눴다.

정확성
보안
성능
테스트
유지보수성
적대적 관점

예를 들어 정확성 리뷰어는 요구사항대로 동작하는지 본다.
보안 리뷰어는 인증/인가나 입력 검증을 본다.
성능 리뷰어는 불필요한 요청이나 N+1 가능성을 본다.
적대적 리뷰어는 일부러 깨뜨리려고 하면 어디서 깨질지 본다.

그 다음에는 gstack의 /qa를 사용했다.

코드 리뷰를 통과해도 실제로 클릭해보면 이상한 경우가 많았다.

모바일에서 버튼이 화면 밖으로 밀린다.
로딩 중에 중복 클릭이 된다.
에러 메시지가 사용자에게 보이지 않는다.
모달을 닫으면 입력값이 사라진다.
특정 화면에서 스크롤이 이상하게 동작한다.

코드 리뷰는 코드의 문제를 찾는다.
QA는 경험의 문제를 찾는다.

둘은 다르다.

그래서 리뷰와 QA를 분리해서 봤다.

---

Phase 5. 학습 축적 — Compound Engineering식 피드백 루프

이 단계가 내가 직접 붙인 Compound Engineering식 흐름이다.

원문에서 말하는 Compound Engineering의 핵심은 이렇게 정리할 수 있다.

각 개발 작업은 다음 개발 작업을 더 쉽게 만들어야 한다.

보통 개발은 기능을 추가할수록 코드베이스가 복잡해진다.

새 기능은 새로운 예외를 만들고,
버그 수정은 그 순간의 문제만 해결하고 지나가며,
몇 주 뒤 비슷한 문제를 다시 디버깅하게 된다.

Compound Engineering은 이 흐름을 반대로 만들려는 접근이다.

기능을 만들고 끝내는 것이 아니라,
그 과정에서 나온 판단과 해결책을 프로젝트 안에 남긴다.

그래서 다음 작업을 시작할 때 AI가 이전의 해결책, 기존 패턴, 프로젝트의 취향, 검증 기준을 읽고 더 나은 출발점에서 작업하게 만든다.

내가 이 방식을 적용한 이유도 비슷했다.

Claude Code를 쓰다 보면 코딩 속도는 빨라진다.
하지만 속도가 빨라진 만큼 같은 실수를 빠르게 반복할 수도 있다.

예를 들면 이런 것들이다.

기존 공통 유틸이 있는데 새로 구현하는 경우
이전에 정한 기획 의도를 무시하고 구현하는 경우
리뷰에서 지적받은 내용을 다음 작업에서 또 반복하는 경우
프로젝트의 파일 구조나 네이밍 규칙을 어기는 경우
테스트를 통과시키기 위해 임시방편으로 코드를 수정하는 경우
인증, 에러 처리, 캐싱 같은 기존 규칙을 놓치는 경우

처음에는 이런 문제를 그때그때 고치고 넘어갔다.

하지만 그렇게 하면 다음 작업에서 같은 문제가 다시 나왔다.
결국 문제는 개별 코드가 아니라, AI가 참고할 수 있는 프로젝트의 기억이 부족하다는 점이었다.

그래서 리뷰가 끝난 뒤 바로 다음 기능으로 넘어가지 않고,
이번 사이클에서 얻은 해결책과 반복 가능한 패턴을 정리하기 시작했다.

흐름은 단순하다.

구현
→ 리뷰
→ QA
→ 문제와 판단 기록
→ 재사용 가능한 해결책 정리
→ docs/solutions에 문서화
→ 반복 규칙은 AGENTS.md 또는 CLAUDE.md에 반영
→ 다음 작업 전에 참조

여기서 중요한 건 단순히 “실수 목록”을 만드는 게 아니다.

원문 기준으로 보면 Compound 단계에는 네 가지 행동이 들어간다.

1. Capture the solution
   이번에 무엇이 문제였고, 어떤 해결책이 효과 있었는지 기록한다.

2. Make it findable
   나중에 다시 찾을 수 있도록 태그, 카테고리, 제목을 붙인다.

3. Update the system
   반복적으로 적용해야 할 규칙은 CLAUDE.md나 AGENTS.md에 반영한다.

4. Verify the learning
   다음번에는 이 문제를 시스템이 자동으로 잡을 수 있는지 확인한다.

그래서 나는 문서를 단순 회고용으로 두기보다,
다음 작업에서 Claude가 읽을 수 있는 형태로 남기려고 했다.

원문에서 소개한 구조를 기준으로 하면 저장 위치는 대략 이렇게 나뉜다.

AGENTS.md 또는 CLAUDE.md
→ 에이전트가 매 세션 읽는 프로젝트 규칙, 취향, 패턴

docs/brainstorms/
→ 요구사항, 문제 정의, 범위, 성공 기준

docs/plans/
→ 구현 계획, 변경 대상 파일, 검증 전략

docs/solutions/
→ 해결된 문제와 재사용 가능한 패턴

특히 Compound 단계에서 중요한 곳은 docs/solutions/에 가깝다.

원문에서는 docs/solutions/ 아래에 이런 식의 카테고리를 둔다.

docs/solutions/
  performance-issues/
  security-issues/
  database-issues/
  integration-issues/
  architecture-patterns/
  design-patterns/
  conventions/
  best-practices/

예를 들어 API 요청 관련 실수가 반복됐다면,
그냥 “다음부터 조심하자”로 끝내지 않고 해결 패턴을 문서로 남긴다.

---
category: conventions
tags: [fetcher, react-query, project-convention]
related_files:
  - shared/api
  - lib/fetcher
  - features/*/queries.ts
---

# API 요청은 기존 fetcher를 우선 사용한다

## 문제

기존 공통 fetcher가 있는데도 새로운 fetch 로직을 직접 구현했다.

## 원인

작업 전에 shared/api 구조와 기존 query hook을 확인하지 않았다.  
프로젝트의 기존 패턴보다 일반적인 구현 방식을 우선했다.

## 해결책

API 요청이 필요한 작업을 시작하기 전에는 반드시 다음을 먼저 확인한다.

- shared/api
- lib/fetcher
- 기존 feature의 query hook
- queryKey 관리 방식

새로운 fetch 로직을 만들기 전에 기존 fetcher로 해결 가능한지 검토한다.

## 다음 작업 전 체크

- 비슷한 API 요청이 이미 구현되어 있는가?
- 기존 fetcher를 사용할 수 있는가?
- queryKey가 feature 단위 규칙을 따르고 있는가?
- 새 패턴을 만들 이유가 명확한가?

그리고 이 내용이 반복적으로 중요하다면 CLAUDE.md나 AGENTS.md에 더 짧은 규칙으로 반영한다.

## API 요청 규칙

- API 요청은 기본적으로 기존 customFetcher를 사용한다.
- 새로운 fetch 로직을 직접 만들기 전에 shared/api, lib/fetcher, 기존 query hook을 확인한다.
- React Query queryKey는 feature 단위 queryKey factory를 우선 사용한다.
- 인증 에러 처리는 개별 컴포넌트에서 중복 처리하지 않는다.

이렇게 하면 문서는 단순한 기록이 아니라,
다음 작업에서 AI가 읽는 프로젝트 규칙이 된다.

새로운 기능을 시작할 때도 이런 식으로 요청했다.

작업을 시작하기 전에 AGENTS.md와 docs/solutions를 먼저 확인해줘.
이전에 정리한 프로젝트 규칙과 해결 패턴을 반영해서 구현 계획을 세워줘.
아직 코드는 수정하지 말고, 먼저 계획만 작성해줘.

이 방식의 효과는 생각보다 컸다.

AI가 완전히 실수를 안 하는 것은 아니다.
하지만 적어도 “전에 이미 고쳤던 문제를 또 고치는 일”은 줄어든다.

특히 장기 프로젝트에서는 이 차이가 크다.

한 번의 작업만 보면 문서를 남기는 시간이 귀찮아 보인다.
하지만 비슷한 기능을 세 번, 네 번 만들기 시작하면 이전 기록이 다음 작업의 출발점이 된다.

예를 들어 처음에는 이런 식으로 매번 설명해야 한다.

이 프로젝트에서는 API 요청을 customFetcher로 처리해.
queryKey는 feature 폴더 안에서 관리해.
인증 에러는 BFF Route Handler에서 처리해.

하지만 Compound 단계가 쌓이면 이렇게 바뀐다.

AGENTS.md와 docs/solutions/conventions를 읽고,
기존 API 패턴에 맞춰 계획을 세워줘.

즉, 매번 반복해서 설명하던 내용을 프로젝트가 기억하게 되는 것이다.

내가 이해한 Compound Engineering의 핵심은 여기에 있다.

코드를 한 번 잘 짜는 것이 아니라,
다음 코드가 더 잘 나오도록 시스템을 개선하는 것.

성공한 결과만 남기는 것이 아니라, 실패한 판단도 남긴다.
왜 틀렸는지, 어떤 규칙을 놓쳤는지, 다음에는 무엇을 먼저 확인해야 하는지 기록한다.

그리고 그 기록을 사람이 읽는 회고 문서로만 두지 않고,
AI가 다음 작업에서 읽을 수 있는 입력값으로 바꾼다.

이것이 내가 수동으로 적용한 Compound Engineering식 피드백 루프다.

---

적용 기준

모든 작업에 이 흐름을 전부 적용할 필요는 없다.

작은 작업에까지 모든 단계를 붙이면 오히려 피곤하다.
하지만 오래 가져갈 프로젝트일수록 Compound step의 가치는 커졌다.

작업 규모	사용 방식	예시
소	바로 수정	오타 수정, 간단한 설정 변경
중	간단한 계획 + 리뷰	작은 버그 수정, API 일부 수정
대	gstack + Superpowers + 리뷰	새 기능 모듈, 인증 흐름 변경
장기 작업	전체 흐름 + Compound step	개인 프로젝트, 대규모 리팩토링, 반복 개선 작업

내 기준으로는 작업이 클수록,
그리고 앞으로 비슷한 작업을 다시 할 가능성이 높을수록 Compound step을 붙이는 편이 좋았다.

특히 아래에 해당하면 기록할 가치가 있었다.

같은 실수가 두 번 이상 반복됐다.
리뷰에서 중요한 지적이 나왔다.
새로운 프로젝트 규칙이 생겼다.
기존 패턴을 바꿀 만한 이유가 있었다.
다음 기능에서도 재사용할 수 있는 해결책이 생겼다.
AI가 자주 놓치는 맥락이 발견됐다.

반대로 단순 오타 수정이나 일회성 변경에는 굳이 길게 기록하지 않았다.

중요한 건 모든 작업을 문서화하는 게 아니라,
다음 작업을 실제로 더 쉽게 만들어줄 지식만 남기는 것이다.

---

요약

이 워크플로우는 gstack, Superpowers, Compound Engineering식 피드백 루프를 하나로 연결한 방식이다.

gstack
→ 무엇을 왜 만들지 검증한다.

Superpowers
→ 어떻게 안정적으로 구현할지 잡는다.

Compound Engineering식 피드백 루프
→ 이번 작업에서 얻은 판단, 실수, 해결책을 다음 작업의 컨텍스트로 남긴다.

Compound Engineering을 내가 이해한 방식으로 정리하면 이렇다.

기능 하나를 만드는 데서 끝내지 않고,
그 과정에서 얻은 지식을 프로젝트의 개발 시스템에 반영하는 것.

즉, Claude Code를 더 잘 쓰는 핵심은 단순히 좋은 프롬프트를 쓰는 데 있지 않았다.

오히려 중요한 것은 작업이 끝난 뒤였다.

이번에 무엇을 배웠는가?
다음에는 무엇을 자동으로 피할 수 있는가?
이 내용을 AI가 다시 읽을 수 있는 곳에 남겼는가?

이 질문을 반복하면 프로젝트 안에 작은 운영 매뉴얼이 생긴다.

그리고 그 매뉴얼이 쌓일수록 AI는 단순한 코딩 도구가 아니라,
점점 그 프로젝트의 맥락을 아는 개발 파트너에 가까워진다.

---

출처 & 참고

• https://www.reddit.com/r/whaaat_ai/comments/1s9f5et/i_stacked_gstack_superpowers_and_compound/
• https://dev.to/imaginex/a-claude-code-skills-stack-how-to-combine-superpowers-gstack-and-gsd-without-the-chaos-44b3
• https://wikidocs.net/347784
• https://wikidocs.net/338139
• https://www.reddit.com/r/ClaudeAI/comments/1sgjmec/the_11step_workflow_i_use_for_every_claude_code/?tl=ko