Claude Code 프롬프트 작성 완벽 가이드

in Tech / Prompt-engineering on Claudecode, 개발, 보안, 데이터베이스, Tdd

이 포스트에서는 Claude Code에 대한 프롬프트 작성 방법과 전략을 상세히 설명합니다.

요약

이 가이드에서는 사용자 인증 시스템 및 데이터베이스 작업을 위한 프롬프트 작성 방법을 제공하고, 테스트 주도 개발(TDD)과 보안 검증 프로세스의 중요성을 강조합니다. 또한, 보안 점검 및 표준 준수를 위한 체크리스트와 프롬프트 활용법을 설명합니다.

배경/문제

많은 개발자들이 새로운 기능을 구현하거나 버그를 수정할 때 포괄적인 프롬프트가 필요하다고 인식하고 있습니다. 이러한 프롬프트는 생산성을 향상시키고 팀 간의 원활한 소통을 보장하는 데 중요한 역할을 합니다. 특히 보안성과 관련된 요소들은 간과되어서는 안 됩니다. 사용자 인증이나 데이터베이스 작업에서 발생할 수 있는 보안 취약점을 예방하기 위해서는 철저한 검토와 반복적인 테스트가 필요합니다.

실패 신호

  • 보안 취약점: 개발 및 배포 후 발생하는 보안 문제는 매우 심각합니다. 예를 들어, 데이터 유출이나 서비스 장애가 발생할 수 있습니다.
  • 기능 실패: 테스트 케이스가 누락되어 기능이 실패하면 사용자의 피드백으로 인해 신뢰도가 현저히 떨어질 수 있습니다.
  • 명확하지 않은 요구 사항: 프롬프트에서 요구 사항이 명확하지 않으면 재작업이 필요하게 되어 전체 개발 일정이 지연될 수 있습니다.

이러한 문제를 해결하기 위해서는 초기 설계 단계에서부터 보안 요구 사항을 명세해야 합니다. 예를 들어, 사용자 인증 시스템에서는 OWASP의 인증 가이드라인을 준수하는 것이 중요하며, SQL 인젝션이나 XSS와 같은 공격으로부터 안전하도록 코드를 작성해야 합니다.

접근/해결 전략

Claude Code를 활용하여 효과적으로 프로그래밍 작업을 진행하기 위해 다섯 가지 주요 영역에서 프롬프트를 작성하는 전략을 채택했습니다. 여기에는 신규 기능 개발, 버그 수정, 데이터베이스 작업 설정, 보안 검토 및 컴플라이언스 검사 등이 포함됩니다.

선택 이유

이 접근 방식은 개발자가 명확한 단계로 진행할 수 있도록 지원하며, 필요한 검토 프로세스를 통해 품질을 보장할 수 있습니다. 각 단계를 문서화함으로써 팀원들과의 의사소통이 용이해 집니다. 또한, 각 진행 단계마다 성과를 검증할 방법을 마련하는 것이 매우 유용합니다.

구현 포인트

프롬프트를 효과적으로 구현하기 위한 각 단계에서 필요한 사항들을 다뤄 보겠습니다.

A. 신규 기능 개발 프롬프트

아래는 OAuth2 기반 사용자 인증 시스템을 구현하기 위한 프롬프트 예시입니다.

## 작업: 사용자 인증 시스템 구현

### 1단계: 계획 수립
먼저 OAuth2 기반 인증 시스템 구현 계획을 세워주세요.
코드 작성은 내가 계획을 승인한 후에 시작하세요.

### 2단계: 아키텍처 분석
1. 현재 코드베이스의 구조를 분석하고 설명해주세요
2. 인증 시스템이 들어갈 위치를 제안해주세요
3. 기존 코드와의 통합 지점을 명시해주세요

### 3단계: 테스트 주도 개발 (TDD)
1. 먼저 다음 요구사항에 대한 테스트를 작성하세요:
   - 사용자 로그인 성공/실패
   - JWT 토큰 생성 및 검증
   - 리프레시 토큰 로직
   - 권한 검증 미들웨어
2. 테스트를 실행하고 실패하는지 확인하세요
3. 테스트가 통과하도록 최소한의 코드를 구현하세요
4. 모든 테스트가 통과할 때까지 반복하세요

### 4단계: 보안 검증
- OWASP 인증 가이드라인 준수 여부 확인
- SQL 인젝션, XSS 방어 코드 포함
- 비밀번호는 bcrypt로 해싱 (최소 10 라운드)
- Rate limiting 구현

### 5단계: 최종 확인
- npm run lint 실행
- npm run typecheck 실행
- 모든 테스트 통과 확인
- 커밋 메시지: "feat: OAuth2 기반 사용자 인증 시스템 구현"

이 프롬프트는 개발자가 명확한 계획을 세우도록 유도합니다. 계획 수립 이후에 실제 구현 단계로 넘어갈 수 있도록 하여 실수를 줄이고, 협업 시 필수적인 의견을 수렴할 수 있습니다. 계획 단계에서는 사용자 요구사항, 인증 프로세스의 흐름, API 설계 등을 명확히 해야 합니다.

각 단계별 진행사항을 계속 기록하는 것이 좋습니다. 예를 들어, 기능 완료 후 팀과 공유하고 피드백을 받을 수 있는 기회를 마련하여 기능이 요구사항에 충족하는지 다시 검토하는 것이 중요합니다. 이러한 문서화 과정은 팀의 지식 공유와 제공하는 프로덕트의 아이디어 개선으로 이어질 수 있습니다.

B. 버그 수정 프롬프트

버그를 수정하기 위한 프롬프트 예시는 다음과 같습니다.

## GitHub 이슈 #123 버그 수정

1. gh issue view 123으로 이슈 상세 내용 확인
2. 버그 재현 시나리오 작성 및 실행
3. 근본 원인 분석 (5 Why 기법 활용)
4. 관련 코드 검색 및 영향 범위 파악
5. 버그를 재현하는 실패 테스트 작성
6. 최소한의 코드 변경으로 버그 수정
7. 회귀 테스트 추가
8. 전체 테스트 스위트 실행
9. 린트 및 타입 체크 통과 확인
10. PR 생성: "fix: [이슈 설명] (#123)"

이와 같은 과정은 버그의 재현 및 근본 원인 분석을 통해 효율적이고 체계적인 접근을 가능하게 합니다. 예를 들어, 특정 브라우저에서 발생하는 버그가 있다면, 해당 버그의 재현 시나리오를 작성하여 팀원들과 공유하는 것이 도움이 됩니다. 또한, 버그 수정에서는 반드시 실패 케이스를 기록하고, 이를 복구하기 위해 추가적인 테스트를 수행해야 합니다.

버그 재현 시나리오를 작성할 때에는 사용자가 어떤 상황에서 해당 버그를 경험했는지 상세히 기록해야 합니다. 예를 들어, 입력값, 버튼 클릭 순서, 사용한 환경 등을 포함시켜야 합니다. 이를 통해 팀원들과의 논의가 원활해지고, 문제가 발생했을 때 신속하게 대처할 수 있게 됩니다.

C. 데이터베이스 설정 프롬프트

데이터베이스 설정을 위한 프롬프트는 다음과 같이 구성할 수 있습니다.

## PostgreSQL 데이터베이스 설정 및 마이그레이션

### 환경 설정
1. MCP PostgreSQL 서버가 연결되어 있는지 확인 (/mcp 명령어 사용)
2. 데이터베이스 연결 테스트 실행

### 스키마 생성
1. 다음 요구사항으로 데이터베이스 스키마 생성:
   - users 테이블: id, email, password_hash, created_at, updated_at
   - sessions 테이블: id, user_id, token, expires_at
   - permissions 테이블: id, user_id, resource, action

2. 인덱스 생성:
   - users.email에 unique 인덱스
   - sessions.token에 인덱스
   - sessions.expires_at에 인덱스

3. 외래 키 제약조건 추가

### 마이그레이션 스크립트
1. migrations/ 폴더에 타임스탬프 기반 마이그레이션 파일 생성
2. up/down 스크립트 모두 포함
3. 트랜잭션으로 감싸서 원자성 보장

### 시드 데이터
개발 환경용 테스트 데이터 생성 (프로덕션에서는 실행하지 않도록 주의)

### 검증
1. 모든 테이블과 인덱스가 올바르게 생성되었는지 확인
2. 외래 키 제약조건 테스트
3. 롤백 스크립트 테스트

환경 세팅은 항상 확인 후 진행해야 하며, 특정 명령어를 통해 쉽게 확인할 수 있는 점이 중요합니다. 데이터베이스 연결 상태를 확인하고 필요하다면 연결 정보를 재확인하여야 합니다. 이는 데이터베이스 작업에서 오류를 줄이기 위한 기본적인 준비 작업입니다.

스키마 생성 및 마이그레이션 과정은 데이터 무결성을 보장하는데 필수적입니다. 각 테이블의 필드와 관계를 명확히 정의하고, 트랜잭션 처리를 통해 데이터의 원자성을 보장해야 합니다. 이외에도 데이터 모델 및 마이그레이션 스크립트의 구성 방식과 실행 시점을 명확히 정의하여 작업의 습관화를 이루어야 합니다.

검증

각 단계가 완료될 때마다 성공 여부를 확인하는 것이 중요합니다. 예를 들어, TDD 절차에서는 작성한 테스트 케이스가 모두 통과하는지를 검증합니다. 테스트가 실패할 경우, 원인을 분석하고 수정하는 과정을 거쳐야 합니다.

Before/After

  • Before: 테스트 실행 시 성공하지 않는 케이스 존재
  • After: 모든 테스트 케이스가 통과하면서 성공적으로 기능 구현

이런 과정을 통해 얻은 문제는 버그 리포트 형태로 팀의 지식 공유 및 향후 대응책 마련에 활용될 수 있습니다. 검증 절차는 개발 과정에서 실수를 줄이고 이로 인해 발생할 수 있는 보안 침해 문제를 예방할 수 있도록 도와줍니다.

성공 판정 기준

  • 모든 작성한 테스트가 통과해야 함
  • 코드가 linting 및 타입 체크를 통과해야 함
  • 모든 포괄적인 에러가 처리되었는지 검증

이와 같은 검증 절차를 마련하면, 개발 과정에서 실수를 줄이고 이로 인해 발생할 수 있는 보안 침해 문제를 예방할 수 있습니다.

대안 비교/트레이드오프

프롬프트 작성 시 고려해야 할 두 가지 대안을 비교해 보겠습니다.

대안 1: 구조적 접근

  • 장점: 모든 단계가 명확히 구분되어 있어 순차적으로 진행할 수 있습니다.
  • 단점: 초기 단계에서 시간 소모가 클 수 있습니다.

대안 2: 비구조적 접근

  • 장점: 유연한 구현이 가능합니다.
  • 단점: 각 단계의 진행이 불확실해질 수 있으며, 요구 사항이 누락될 가능성이 있습니다.

선택 기준

구조적 접근이 더 적합한 이유는 명확한 요구 사항 수립과 팀원 간의 커뮤니케이션을 원활하게 하여 오류를 최소화할 수 있기 때문입니다. 비구조적 접근은 초기에는 빠르게 진행할 수 있지만, 결과적으로 재작업이 많아질 수 있으므로 주의해야 합니다. 비구조적 접근을 사용해야 할 경우에는 자주 팀원들과 소통하고 진행 상황을 점검하여 모든 요구 사항을 충족할 수 있도록 해야 합니다.

마무리

이 가이드는 Claude Code를 통한 효과적인 프로그래밍 프롬프트 작성 및 관리의 중요성을 강조하고 있습니다. 개발 과정에서 체크리스트를 준비하여 다음을 확인하세요:

  • 모든 단계가 완벽히 이행되었는가?
  • 문서화는 충분히 이루어졌는가?
  • 보안 검토가 반드시 수행되었는가?

이러한 프롬프트의 체계적인 활용은 개발 및 배포 작업의 품질을 보장하고 보안성을 강화하는 데 기여할 것입니다. 프롬프트 작성 시 각 단계의 중요성을 명확히 이해하고 체계적으로 관리하여 개발 효율성과 코드 품질을 모두 향상시키는 것이 중요합니다.

© 2024. Chiptune93 All rights reserved.