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

(every.to)

22P by neo 5시간전 | ★ favorite | 댓글과 토론

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" (일반적 실수 플래그)
다음 주 반복, 노트 참조, 두 번째 계획이 첫 번째보다 나은지 확인, 몇 달 후 개발자의 사고방식을 아는 시스템 구축