AI에게 시니어 엔지니어처럼 생각하도록 가르치기

• AI 코딩 도구에 코드 작성 전 계획 수립을 먼저 시키는 방법론으로, 잘못된 구현을 방지하고 개발 속도를 높일 수 있음
• 8가지 계획 전략을 난이도별로 적용하며, 각 전략은 특정 에이전트가 병렬로 연구를 수행한 뒤 개발자가 판단과 의사결정을 내리는 구조
• 각 전략은 버그 재현, 베스트 프랙티스 검색, 기존 코드베이스 분석, git 히스토리 조사 등을 포함하며, 에이전트가 학습한 선호도와 패턴이 자동으로 축적됨
• 오픈소스로 공개된 시스템을 Claude Code에 설치하거나, 단일 기능부터 시작해 점진적으로 개발자의 사고방식을 AI에 학습시킬 수 있음

---

AI 계획 중심 개발 방식

• AI가 코드를 작성하기 전 계획을 수립하도록 하는 접근법 소개
  • 이 방식은 단순히 코드를 작성하는 것보다 기능 구현 속도를 높이고 오류를 줄이는 효과를 냄
• 예시로, 이메일 관리 앱 Cora의 ‘이메일 파산(email bankruptcy)’ 기능 개발 과정 소개
  • 53,000개의 이메일을 중요 메일 손실 없이 정리하는 기능 구현 시, AI 연구 에이전트가 사전 분석을 수행함
  • Gmail의 2,000건 제한, 시스템 타임아웃, 사용자 대기 시간 문제를 사전에 발견해 잘못된 구현을 방지함

8가지 계획 전략

전략 1: 버그 재현 및 문서화

• 목적: 수정 전 버그를 재현하고 단계별 가이드 생성
• 사용 시점: Fidelity 1~2, 특히 버그 수정 시
• 이메일 파산 기능 출시 직후 19명의 사용자가 작업 실패 상태에 갇힌 문제 발생
  • AppSignal 로그를 순회하며 진단한 결과, Gmail 속도 제한 에러가 프로덕션에서 무시되고 있었음
  • 배치 하나가 실패하면 전체 작업이 중단되었으나 사용자에게 알리지 않아, 사용자는 무한 로딩 스피너만 보게 됨
• 재현 과정에서 배치 처리와 작업 재개 기능이 필요함을 발견, 단순 재시도만으로는 부족함을 확인
• 복리 효과: @kieran-rails-reviewer 에이전트의 체크리스트에 "외부 API를 호출하는 백그라운드 작업 시 속도 제한 처리 여부, 재시도 여부, 부분 상태 방치 여부" 항목 추가

전략 2: 베스트 프랙티스 조사

• 목적: 유사 문제 해결 사례를 웹에서 검색
• 사용 시점: 모든 난이도, 특히 생소한 패턴
• 2버전 뒤처진 gem 업그레이드 시 에이전트가 "버전 X에서 Y로 업그레이드 경로", "버전 간 중단 변경사항", "일반적 마이그레이션 이슈" 검색
  • 공식 업그레이드 가이드와 동일 업그레이드를 수행한 엔지니어들의 블로그 포스트 3개 발견
  • 3분 연구로 수 시간의 시행착오 디버깅 방지
• 비기술적 결정에도 활용: "SaaS 가격 티어 베스트 프랙티스", "이메일 드립 캠페인 전환 카피", "백그라운드 작업 재시도 전략" 등
• 복리 효과: 유용한 패턴 발견 시 자동으로 `docs/*.md` 파일에 저장, 다음번 유사 질문 시 웹 검색 전에 먼저 확인

전략 3: 코드베이스 조사

• 목적: 기존 코드에서 유사 패턴 탐색
• 사용 시점: 기존 기능 중복 가능성이 있는 모든 작업
• 새 기능에 이벤트 트래킹 추가 전 에이전트가 코드베이스 검색: "현재 이벤트 트래킹 처리 방식은?", "분석 호출 패턴은?", "이벤트 전송 위치는?"
  • 헬퍼 메서드까지 갖춘 기존 트래킹 시스템 발견 (본인이 잊고 있었음)
  • AI가 코드베이스를 참조하지 않으면 처음부터 새로 만들려고 시도함
• 새 트래킹 시스템을 만드는 대신 기존 패턴 확장으로 해결, 호환되지 않는 두 번째 시스템 구축 방지
• 복리 효과: "@event-tracking-expert" 에이전트 생성, 트래킹이 필요한 모든 기능 계획 시 자동 실행

전략 4: 라이브러리 소스코드 조사

• 목적: 설치된 패키지 및 gem의 소스코드 직접 읽기
• 사용 시점: 빠르게 변화하거나 문서화가 부족한 라이브러리 사용 시
• RubyLLM gem은 새 모델, 파라미터, 기능이 지속적으로 추가되지만 문서가 뒤처짐
  • 에이전트가 RubyLLM 소스코드 분석: "사용 가능한 모델 옵션은?", "전달 가능한 파라미터는?", "최신 버전의 미문서화 기능은?"
  • "버전 1.9에 스트리밍 지원 추가되었으나 문서화 안 됨. 테스트 스위트의 파라미터명과 사용 예시" 제공
• 복리 효과: 의존성 업데이트 시마다 지식도 자동 업데이트, 낡은 정보로 작업하는 일 없음

전략 5: git 히스토리 연구

• 목적: 커밋 히스토리 분석으로 과거 결정의 의도 파악
• 사용 시점: 리팩토링, 작업 이어가기, "왜" 이해가 필요할 때
• 구버전 EmailClassifier 사용 중 발견, 업그레이드 시도 전 git 히스토리 검색: "왜 v1 사용 중인가?", "v2 업그레이드 시도한 적 있나?"
  • 3개월 전 다른 팀원의 PR 발견: v2로 업그레이드했다가 받은편지함 이메일이 아카이브로, 아카이브 이메일이 받은편지함으로 가는 문제 발생
  • PR 토론에 상세한 이유와 함께 의도적으로 롤백한 기록 존재
• 복리 효과: 제도적 기억이 보존되고 검색 가능해짐, 신입 팀원이 과거 결정의 논리를 물려받음

전략 6: 프로토타이핑으로 요구사항 명확화

• 목적: 별도 환경에서 빠른 프로토타이핑으로 요구사항 명확화
• 사용 시점: Fidelity 3, UX 불확실성, 탐색적 작업
• 이메일 Brief 인터페이스 재설계 시 5가지 다른 레이아웃 프로토타입을 Claude에서 각 5분씩 제작
  • 직접 클릭해보고 불편한 점 파악, 일부 사용자에게 최적 버전 제시
  • 한 사용자 피드백: "레이아웃이 압도적이고 이메일 아카이브 방법을 모르겠음"
• 해당 인사이트가 실제 계획의 요구사항으로 반영: "아카이브 버튼은 좌측 상단 모서리 배치 필수—사용자 근육 기억이 Gmail에서 그 위치 기대"
• 복리 효과: 프로토타이핑이 불확실성을 구체적 명세로 전환, 사용자 반응을 문서화

전략 7: 옵션과 함께 종합

• 목적: 모든 연구를 트레이드오프가 포함된 하나의 계획으로 통합
• 사용 시점: 연구 단계 종료, 구현 전
• 전략 1~6 실행 후 에이전트가 종합: "이 연구를 바탕으로 문제 해결 방법 3가지 제시. 각 접근법의 구현 복잡도, 성능 영향, 유지보수 부담, 매칭되는 기존 패턴"
• Gmail 인박스 동기화 예시:
  • 옵션 A—기존 동기화 시스템 사용: 빠른 구현, 하지만 코드 중복 및 관심사 분리 저해
  • 옵션 B—실시간 동기화: 깔끔한 아키텍처, 하지만 느리고 신뢰성 문제 가능
  • 옵션 C—미러 캐싱 시스템 구축: 최고의 장기 솔루션, 가장 깔끔한 분리, 하지만 초기 작업량 최대
• 비교 확인 후 30초 만에 정보에 입각한 선택 가능
• 복리 효과: 선택이 선호도를 드러냄, "호환성 우선" 선호 표시 시 다음번 유사 결정 때 시스템이 호환성에 높은 가중치 부여

전략 8: 스타일 에이전트 리뷰

• 목적: 완성된 계획을 개발자 선호도 체크용 특화 리뷰어에게 전달
• 사용 시점: 최종 계획 단계, 구현 전
• 자동 실행되는 3개 리뷰 에이전트:
  • 단순화 에이전트: 과도한 엔지니어링 플래그, "이 기능에 정말 3개 데이터베이스 테이블 필요한가? 타입 필드가 있는 1개 테이블로 가능하지 않나?"
  • 보안 에이전트: 일반적 취약점 체크, "이 계획은 사용자 입력을 데이터베이스 쿼리에 직접 허용—입력 새니타이제이션 추가 필요"
  • Kieran 스타일 에이전트: 개인 선호도 강제, "복잡한 조인 사용 중, Kieran은 단순 쿼리 선호, 비정규화 고려"
• 복리 효과: 에이전트가 시간이 지남에 따라 개발자 취향 축적, "이거 싫어함" 또는 "잘 잡았어" 표시 시 시스템이 학습

시작하기

오늘 바로 시도할 수 있는 방법

• Every의 Github 마켓플레이스에 계획 시스템 오픈소스 공개
• Claude Code에 설치하면 /plan 슬래시 커맨드와 연구 에이전트 즉시 사용 가능
• Claude Code 또는 Droid에서 플러그인 사용 가능

단순한 시작 방법

• 이번 주 빌드 중인 Fidelity 2 기능 하나 선택: 여러 파일에 걸치고 명확한 범위를 가진 작업 (새 뷰 추가, 피드백 시스템 구현, 컴포넌트 리팩토링)
• Claude Code나 Cursor에 빌드 요청 전 15~20분 연구:
  1. 베스트 프랙티스: 다른 사람들은 어떻게 해결했는가? 웹에서 블로그 포스트, Stack Overflow, 문서 검색
  2. 본인의 패턴: 본인은 어떻게 해결했는가? 기존 코드베이스에서 유사 기능 검색
  3. 라이브러리 기능: 사용 중인 도구가 실제로 무엇을 지원하는가? AI로 문서나 소스코드 읽기
• AI가 연구를 다음 항목을 포함한 계획으로 종합하도록 함:
  1. 해결할 문제 (명확한 한 문장)
  2. 2~3가지 솔루션 접근법 (각각의 정직한 장단점)
  3. 매칭되어야 할 기존 코드 패턴
  4. 엣지 케이스 또는 보안 고려사항
• 계획 검토 및 반응 관찰: "너무 복잡하다" 또는 "이미 더 나은 방법 있다" 생각 시, 계획만 수정하지 말고 왜 그렇게 생각하는지 포착해 기록
• 계획 기반으로 기능 출시, 최종 구현과 원래 계획 비교, 어디서 벗어났는가? 왜? 무엇이 계획을 더 낫게 만들었을까?
• 10분 투자해 학습 하나 성문화: CLAUDE.md 파일에 추가, "X 타입 작업 시 Y 체크 기억" 또는 "이유 C 때문에 접근법 B보다 A 선호" 같은 규칙 하나 작성
• 학습 축적 후 특화 연구 에이전트나 커맨드 생성: "Event Tracking Expert" (본인 패턴 숙지), "Security Checker" (일반적 실수 플래그)
• 다음 주 반복, 노트 참조, 두 번째 계획이 첫 번째보다 나은지 확인, 몇 달 후 개발자의 사고방식을 아는 시스템 구축