AI 생성 코드의 품질은 무엇을 어떻게 요청하느냐에 거의 전적으로 달려 있습니다. 이 가이드는 Claude Code에서 일관되게 더 나은 결과를 만드는 패턴을 다룹니다.
작업 범위 지정부터 시스템 프롬프트까지, 반복적 개선부터 역할별 지시까지. 다음 코딩 세션에서 적용할 수 있는 실용 기법.
인간 개발자에게 '로그인 페이지를 만들어 달라'고 하면 확인 질문을 합니다. 어떤 인증 제공자? 어떤 필드? OAuth를 처리해야 하나? 에러 메시지는? 로딩 상태는?
AI 코딩 에이전트는 이 모든 질문에 스스로 답하려 합니다. 맞출 때도 있습니다. 하지만 합리적이지만 원하는 것과 다른 것을 추측하는 경우가 많습니다. '합리적'과 '정확히 맞는 것' 사이의 간극을 프롬프트 엔지니어링이 메웁니다.
좋은 프롬프트가 길 필요는 없습니다. 중요한 것에 구체적이고 그렇지 않은 것에는 침묵해야 합니다. 그 균형이 이 가이드의 주제입니다.
작업에 관계없이 결과를 개선하는 패턴.
'React 컴포넌트를 만들고, 상태를 추가하고, 스타일링' 대신 최종 결과를 설명하세요: '프로젝트 이름을 표시하고, 드래그 정렬을 지원하며, 기존 Tailwind 테마를 사용하는 접이식 사이드바를 구축.' 방법은 에이전트가 결정하게 하세요.
Avoid
컴포넌트를 만들어. useState를 추가해. 토글 버튼을 추가해. Tailwind로 스타일링.
Better
프로젝트를 이름으로 나열하는 접이식 사이드바 컴포넌트를 구축. 드래그 정렬을 지원하고 다크 테마(bg-[#1a1a2e], border-[#2a2a40])와 매치. 접힌 상태는 페이지 새로고침 간 유지.
에이전트는 경계를 알 때 가장 잘 작동합니다. 어떤 파일을 다룰지(또는 피할지), 어떤 패턴을 따를지, '완료'가 어떻게 보이는지 지정하세요. 범위가 없는 작업은 리뷰하기 어려운 광범위한 변경으로 이어집니다.
Avoid
인증 시스템을 리팩토링해.
Better
src/api/auth/login.ts의 로그인 핸들러를 리팩토링하여 비밀번호 해싱에 sha256 대신 bcrypt를 사용. JWT 로직이나 세션 쿠키 처리는 변경하지 말 것. tests/auth/의 관련 테스트를 업데이트.
Claude Code는 프로젝트 파일을 읽을 수 있지만 당신의 생각은 읽을 수 없습니다. 따르는 규칙, 선호하는 라이브러리, 이미 확립된 패턴이 있다면 말하세요. 재작업을 줄여줍니다.
Avoid
폼 유효성 검사를 추가해.
Better
zod를 사용하여 회원가입 폼에 유효성 검사를 추가(src/forms/settings.ts의 설정 폼에서 이미 사용 중). 각 필드 아래에 인라인 에러 메시지 표시. 로그인 폼과 동일한 에러 스타일링을 따를 것.
복합 프롬프트('API 구축, 테스트 작성, 문서 업데이트, 배포')는 에이전트에게 동시에 너무 많은 목표를 부여합니다. 복잡한 작업을 순차적이고 집중된 작업으로 나누세요. 각각은 이전 결과를 기반으로 합니다.
Avoid
사용자 프로필 페이지 구축, API 엔드포인트 작성, 테스트 추가, README 업데이트, 그리고 네비게이션 바도 수정.
Better
GET /api/user/profile 엔드포인트를 구축. id, name, email, plan 필드를 반환. 기존 인증 미들웨어를 사용.
첫 결과가 맞지 않으면 처음부터 다시 하지 말고 프롬프트를 개선하세요. Claude는 전체 대화 컨텍스트를 유지합니다. 무엇이 잘못되었는지, 무엇을 바꿀지, 무엇을 유지할지 말하세요. 반복이 재발명보다 빠릅니다.
Avoid
잘못됐어. 처음부터 다시 해서 컴포넌트를 다르게 만들어.
Better
레이아웃은 좋지만 모바일 브레이크포인트가 잘못됨. 768px 이하에서는 그리드 대신 카드를 수직으로 쌓을 것. 나머지는 모두 그대로 유지.
시스템 프롬프트는 당신이 무엇을 말하기 전에 에이전트의 기본 행동을 설정합니다. AI 코딩에서 가장 활용이 부족한 도구입니다.
시스템 프롬프트는 에이전트에게 자신이 누구이며, 무엇에 집중하고, 무엇을 피해야 하는지 알려줍니다. 세션의 모든 메시지에 적용됩니다. 에이전트의 직무 기술서라고 생각하세요.
AgentsRoom에는 14개의 역할별 시스템 프롬프트가 포함되어 있습니다. 프론트엔드 에이전트 프롬프트는 컴포넌트, 접근성, 반응형 디자인에 집중하도록 지시합니다. QA 에이전트 프롬프트는 에지 케이스를 생각하고 포괄적인 테스트를 작성하도록 지시합니다. 커스터마이징하거나 직접 작성할 수도 있습니다.
당신은 시니어 프론트엔드 개발자입니다. React 컴포넌트, CSS/Tailwind 스타일링, 접근성(WCAG AA), 반응형 디자인에 집중하세요. 새 컴포넌트를 만들기 전에 프로젝트의 기존 컴포넌트 라이브러리를 사용하세요. 상속보다 합성을 선호. 시맨틱 HTML을 작성. 백엔드 파일은 절대 수정하지 마세요.
가장 효과적인 프롬프트는 채팅에 입력하는 것이 아닙니다. 리포지토리에 존재합니다.
CLAUDE.md는 프로젝트 루트에 있는 markdown 파일로 Claude Code가 자동으로 읽습니다. 프로젝트 구조, 규칙, 스택 세부사항, 모든 에이전트 세션에 적용되는 가이드라인을 포함합니다.
'Tailwind CSS 4, Prisma ORM, Next.js 16을 사용합니다'를 매번 반복하는 대신 CLAUDE.md에 한 번 작성하세요. 모든 에이전트가 이 컨텍스트를 상속합니다. AgentsRoom에는 CLAUDE.md 내장 편집기가 포함되어 있습니다.
잘 작성된 CLAUDE.md는 수십 개의 개별 프롬프트보다 가치가 있습니다. 축적됩니다: 모든 세션이 그 혜택을 받습니다.
같은 지시를 다시 쓰지 마세요. 효과적인 것을 저장하고 재사용하세요.
프로젝트마다 같은 유형의 요청을 작성한다면('이 파일의 유닛 테스트 작성', '리포지토리 패턴으로 리팩토링', '모든 API 라우트에 에러 처리 추가'), 재사용 가능한 프롬프트로 저장하세요.
AgentsRoom에는 두 레벨의 프롬프트 라이브러리 기능이 있습니다: 프로젝트별 프롬프트와 어디서나 사용하는 패턴용 글로벌 프롬프트(클라우드 동기화).
좋은 라이브러리 후보: 코드 리뷰 체크리스트, 테스트 작성 템플릿, 마이그레이션 스크립트, 컴포넌트 스캐폴딩 지시, 보안 감사 단계. 팀 위키에 표준 절차로 넣을 만한 것.
[파일]의 유닛 테스트를 작성. vitest 사용. 정상 경로, 에지 케이스(빈 입력, null, 잘못된 타입), 에러 처리를 커버. 외부 의존성 모킹. 브랜치 커버리지 90% 이상 목표.
현재 git diff의 변경사항을 리뷰. 확인 항목: 미사용 임포트, 누락된 에러 처리, 타입 안전성 문제, 잠재적 레이스 컨디션, 네이밍 불일치. 발견된 각 문제의 수정을 제안.
[리소스]의 REST 엔드포인트를 생성. zod 입력 검증, 적절한 에러 응답(400, 401, 404, 500), 요청/응답 TypeScript 타입, JSDoc 주석을 포함. src/api/의 기존 패턴을 따를 것.
단일 프롬프트를 넘는 복잡한 작업을 위한 기법.
큰 작업을 순서가 있는 단계로 분할합니다. 첫 번째 에이전트를 1단계로 시작하고, 완료를 기다린 후, 다음 에이전트를 2단계로 시작합니다(1단계 출력 참조). 각 단계는 더 작고 집중적입니다. 예시: 에이전트 1이 DB 스키마 설계, 에이전트 2가 그 스키마로 API 작성, 에이전트 3이 API 테스트 작성.
한 에이전트가 완료되면 다른 에이전트를 그 출력에 지정합니다. '프론트엔드 에이전트가 src/components/에서 한 변경사항을 리뷰. 접근성 문제와 누락된 에러 상태를 확인.' 다른 역할의 새 에이전트가 원래 에이전트의 놓친 부분을 발견합니다.
넓은 프롬프트로 시작하여 에이전트의 접근 방식을 확인합니다. 후속 메시지에서 제약을 추가: '좋은 구조지만 클라이언트 컴포넌트 대신 서버 컴포넌트를 사용해.' '훅은 유지하되 useEffect를 제거하고 React Query 뮤테이션을 사용해.' 각 반복이 원하는 솔루션에 가까워집니다.
에이전트에게 기존 코드를 가리킵니다: 'src/pages/profile.tsx와 동일한 패턴으로 설정 페이지를 구축. 같은 레이아웃 구조, 같은 폼 처리, 같은 에러 표시.' 이것이 말로 패턴을 설명하는 것보다 효과적인 경우가 많습니다.
일관되게 나쁜 결과를 만드는 패턴.
어떤 함수를 쓸지, 어떤 변수명을 지을지, 어떤 순서로 구현할지 에이전트에게 정확히 지시하는 것. 이 마이크로매니지먼트는 에이전트가 더 나은 접근법을 찾는 능력을 제거합니다. 절차가 아닌 결과를 설명하세요.
에이전트에게 제약 없이 '코드베이스를 개선해'라고 요청하는 것. 경계가 없으면 에이전트가 건드리길 원하지 않는 파일을 리팩토링하거나, 다른 코드가 의존하는 API를 변경하거나, 낮은 우선순위 개선에 토큰을 소비할 수 있습니다.
프로젝트에 이미 패턴, 유틸리티, 컴포넌트가 존재한다는 것을 언급하지 않는 것. 에이전트는 새것을 만듭니다. 'src/hooks/에 useAuth 훅이 이미 있다'는 한마디가 상당한 재작업을 줄입니다.
다섯 가지 작업을 하나의 메시지에 넣는 것. 에이전트가 모두 시도하지만, 경쟁하는 목표를 다루면서 품질이 떨어집니다. 순차적이고 집중된 요청으로 나누세요.
AgentsRoom은 시스템 프롬프트, 프롬프트 라이브러리, CLAUDE.md 편집을 기본 제공합니다. 프롬프트 작성 시간은 줄이고 구축 시간은 늘리세요.