AI CLI 도구 모범 사례

도구 선택 가이드

비교 매트릭스

결정 트리

Q: 무료로 사용하고 싶다?
└─ Yes → Continue + Ollama 또는 Aider + Ollama
└─ No → Q: IDE 내부에서 사용하고 싶다?
   └─ Yes → Q: 최고 품질이 필요하다?
      └─ Yes → Cursor Pro (변동/월)
      └─ No → Continue (API 키 사용)
   └─ No → Q: 터미널 전용인가?
      └─ Yes → Q: 명령어만 필요한가?
         └─ Yes → GitHub Copilot CLI
         └─ No → Claude CLI 또는 Aider
      └─ No → Cline (자율 에이전트)

작업별 추천

멀티 도구 전략

하나의 도구만 고집하지 말고, 상황에 맞게 조합하세요.

# 추천 조합 1: 무료 중심
- IDE 작업: Continue + Ollama
- Git 통합: Aider + Ollama
- 터미널: 직접 입력 또는 alias

# 추천 조합 2: 균형형
- IDE 작업: Continue (Claude API)
- 복잡한 작업: Claude CLI
- 터미널: GitHub Copilot CLI

# 추천 조합 3: 프리미엄
- 주 도구: Cursor Pro
- 자율 작업: Cline (Claude API)
- 터미널: GitHub Copilot CLI

# 추천 조합 4: 전문가
- 빠른 편집: Cursor (Cmd+K)
- 프로젝트 관리: Claude CLI
- Git: Aider
- 자율 작업: Cline

Codex 워크플로우

Codex는 CLI/IDE/웹에서 병렬 작업을 수행하는 코딩 에이전트입니다. CLI 기반 워크플로우와 보안 흐름은 전용 가이드에서 확인하세요.

• 승인 모드: 제안 → 자동 수정 → 자율 실행 순서로 단계적으로 확장
• 샌드박스: 클라우드 작업은 격리된 환경에서 실행
• 권한 통제: 네트워크/파일 접근은 승인 정책으로 제한

• Codex 가이드 - 개요, 사용 흐름, 보안/거버넌스

효과적인 프롬프팅

프롬프트 작성 원칙

1. 명확성 (Clarity)

"웹사이트 만들어줘."

"React + TypeScript로 블로그 웹사이트 만들어줘.

기능:
- 마크다운 글 작성
- 카테고리별 분류
- 검색 기능
- 반응형 디자인

기술 스택:
- Next.js 13 (App Router)
- TypeScript
- Tailwind CSS
- Contentlayer (마크다운 처리)

파일 구조:
- app/ (페이지)
- components/ (재사용 컴포넌트)
- content/ (마크다운 글)
- lib/ (유틸리티)

처음부터 끝까지 설정하고 개발 서버 실행까지 해줘."

2. 컨텍스트 (Context)

# 프로젝트 컨텍스트 제공
"이 프로젝트는 Next.js 13 프로젝트야.
현재 App Router를 사용 중이고,
Tailwind CSS로 스타일링하고 있어.

블로그 글에 댓글 기능 추가해줘.
기존 코드 스타일을 유지하면서."

# 도구별 컨텍스트 참조
# Claude CLI: .claude/instructions.md
# Cursor: @Files, @Codebase
# Continue: @file, @codebase
# Aider: /add file.js

3. 구체성 (Specificity)

4. 단계별 접근 (Step-by-step)

# 복잡한 작업은 단계별로

# 1단계
"먼저 프로젝트 초기 설정만 해줘.
Next.js + TypeScript + Tailwind 설정."

# 2단계 (1단계 완료 후)
"좋아. 이제 블로그 글 목록 페이지 만들어줘.
Contentlayer로 마크다운 파싱."

# 3단계
"목록 페이지 잘 작동해. 이제 개별 글 페이지 만들어줘."

# 4단계
"완벽해! 마지막으로 검색 기능 추가해줘."

프롬프트 템플릿

템플릿 1: 새 기능 추가

[기능명]을 추가해줘.

요구사항:
- [기능 1]
- [기능 2]
- [기능 3]

기술 스택:
- [프레임워크]
- [라이브러리 1]
- [라이브러리 2]

제약사항:
- [제약 1]
- [제약 2]

예상 파일:
- [파일 1]
- [파일 2]

테스트:
[테스트 방법]

템플릿 2: 버그 수정

[파일명]에서 [에러 타입] 발생해.

에러 메시지:
[에러 로그 전체]

재현 방법:
1. [단계 1]
2. [단계 2]
3. [에러 발생]

예상 원인:
[추측 가능하면]

수정 후 확인:
[테스트 방법]

템플릿 3: 리팩토링

[파일명 또는 모듈]을 리팩토링해줘.

목표:
- [목표 1: 예- 중복 코드 제거]
- [목표 2: 예- TypeScript strict 모드 적용]
- [목표 3: 예- 성능 최적화]

유지할 것:
- [기능 유지]
- [API 호환성]

개선 방향:
- [구체적인 개선안]

테스트:
기존 테스트가 모두 통과해야 함

고급 프롬프팅 기법

1. 역할 부여 (Role Assignment)

"당신은 시니어 React 개발자입니다.
Next.js 13 App Router와 TypeScript에 정통합니다.
성능 최적화와 접근성을 중요시합니다.

이 컴포넌트를 최적화해주세요."

2. 제약 조건 명시 (Constraints)

"다음 제약 조건을 반드시 지켜주세요:
- 외부 라이브러리 추가 금지 (현재 의존성만 사용)
- 기존 API 호환성 유지
- 브라우저 호환: IE11 제외, 모던 브라우저
- 파일 크기: 최대 200줄
- 성능: Lighthouse 점수 90점 이상"

3. 예시 제공 (Examples)

"다음과 같은 스타일로 코드 작성해줘:

예시 (기존 코드):
```typescript
export const fetchUser = async (id: string): Promise => {
  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) throw new Error('Failed to fetch');
    return await response.json();
  } catch (error) {
    console.error('fetchUser error:', error);
    throw error;
  }
};
```

이 스타일을 따라서 fetchPosts 함수 만들어줘."

4. 반복 개선 (Iteration)

# 첫 번째 시도
"React 버튼 컴포넌트 만들어줘."

# 피드백 및 개선
"좋아. 이제 여기에 다음을 추가해줘:
- loading 상태
- disabled 상태
- 아이콘 지원
- 다양한 크기 (sm, md, lg)"

# 추가 개선
"완벽해. 마지막으로 Storybook 스토리도 작성해줘."

워크플로우 최적화

개발 플로우

워크플로우 1: 새 프로젝트 시작

# 1. Git 초기화
git init
git add .
git commit -m "Initial commit"

# 2. 프로젝트 지시사항 작성
# Claude CLI: .claude/instructions.md
# Cursor: .cursorrules
# Aider: .aider.conf.yml

# 3. AI 도구로 초기 구조 생성
# Cline 또는 Claude CLI 사용 (자율성 높음)

# 4. 첫 커밋
git add .
git commit -m "feat: Initial project structure

Co-Authored-By: Claude "

워크플로우 2: 기능 개발

# 1. 브랜치 생성
git checkout -b feature/user-auth

# 2. AI에게 요청 (명확하고 구체적으로)
# Continue 또는 Cursor 사용 (IDE 통합)

# 3. 코드 검토
# AI가 생성한 코드를 항상 검토!

# 4. 테스트
npm test
npm run dev  # 브라우저에서 확인

# 5. 커밋
git add .
git commit -m "feat: Add user authentication

- JWT token-based auth
- Login/signup endpoints
- Protected routes

Co-Authored-By: Claude "

# 6. 푸시
git push origin feature/user-auth

워크플로우 3: 버그 수정

# 1. 버그 재현
npm run dev
# 에러 발생 확인

# 2. 에러 로그 복사
# 전체 스택 트레이스 포함

# 3. AI에게 요청
# 에러 로그와 함께 파일 컨텍스트 제공
# Continue @terminal 또는 Cline 사용

# 4. 수정 확인
npm test
npm run dev

# 5. 커밋
git add .
git commit -m "fix: Resolve TypeError in UserList

Cannot read property 'map' of undefined
Added optional chaining

Fixes #123"

워크플로우 4: 리팩토링

# 1. 테스트 확인 (리팩토링 전)
npm test  # 모두 통과 확인

# 2. AI에게 리팩토링 요청
# Cursor Composer 또는 Claude CLI

# 3. 변경사항 검토
git diff

# 4. 테스트 재실행
npm test  # 여전히 통과하는지 확인

# 5. 커밋
git add .
git commit -m "refactor: Convert utils to TypeScript

- Split into smaller modules
- Add strict type checking
- Improve error handling"

Git 통합 모범 사례

1. 자주 커밋

# AI가 여러 파일 변경 후 바로 커밋
git add .
git commit -m "feat: Add authentication system"

# 다음 기능 추가
# AI에게 요청...

# 또 커밋
git add .
git commit -m "feat: Add email verification"

# 장점: 문제 생기면 쉽게 되돌리기
git revert HEAD  # 마지막 커밋만 취소

2. 명확한 커밋 메시지

# 나쁜 예
git commit -m "update"
git commit -m "fix bug"

# 좋은 예
git commit -m "feat: Add user authentication with JWT

- Implement login/signup endpoints
- Add JWT middleware
- Create User model with bcrypt hashing

Co-Authored-By: Claude "

# Conventional Commits 규칙
feat:     새 기능
fix:      버그 수정
refactor: 리팩토링
docs:     문서
test:     테스트
chore:    빌드, 설정

3. Co-Authored-By 추가

# AI가 생성한 코드는 명시
git commit -m "feat: Add search functionality

Co-Authored-By: Claude Sonnet (균형) "

# 또는 Cursor
Co-Authored-By: Cursor AI 

# 또는 GitHub Copilot
Co-Authored-By: GitHub Copilot 

4. .gitignore 철저히

# .gitignore
.env
.env.local
*.log
node_modules/
dist/
build/

# AI 도구 관련
.cursor/
.continue/
.aider*

# API 키 절대 커밋 금지!

효율성 팁

1. 단축키 숙달

   Cursor: Cmd+K (편집), Cmd+L (채팅)
   Continue: Cmd+I (인라인), Cmd+L (채팅)
   VS Code: Cmd+P (파일 찾기), Cmd+Shift+P (명령)

2. 별칭 설정

   # ~/.zshrc
   alias cl='npx claude'
   alias ghcs='gh copilot suggest'
   alias ghce='gh copilot explain'

3. 스니펫 활용

   # VS Code 스니펫
   "Prompt for feature": {
     "prefix": "aiprompt",
     "body": [
       "변동 기능 추가해줘.",
       "",
       "요구사항:",
       "- 변동",
       "",
       "기술 스택:",
       "- 변동"
     ]
   }

비용 최적화

무료 옵션

전략 1: Ollama 활용

# Ollama 설치 (한 번만)
curl -fsSL https://ollama.com/install.sh | sh

# 모델 다운로드
ollama pull llama3.2         # 범용 (2GB)
ollama pull deepseek-coder-v2  # 코딩 특화 (8.9GB)
ollama pull starcoder2:3b    # 자동완성 (1.7GB)

# Continue + Ollama
# config.json에서 Ollama 설정
# → 완전 무료!

# Aider + Ollama
aider --model ollama/llama3.2
# → 완전 무료!

# 장점
- 비용 변동
- 프라이버시 (코드가 외부로 나가지 않음)
- 오프라인 작업 가능

# 단점
- 품질이 Claude/GPT-4보다 낮음
- 로컬 컴퓨팅 리소스 필요

전략 2: 무료 티어 활용

비용 절감 전략

1. 적절한 모델 선택

2. 명확한 프롬프트로 재시도 방지

# 나쁜 예 (비용 낭비)
"앱 만들어줘"  # → 모호함
"아니야, React로"  # → 재시도
"TypeScript 사용해"  # → 또 재시도
# → 3배 비용!

# 좋은 예 (비용 절감)
"React + TypeScript 앱 만들어줘..."  # → 한 번에 성공
# → 1배 비용

3. Prompt Caching 활용

# Claude API의 Prompt Caching
# 반복되는 긴 컨텍스트를 캐싱 (90% 비용 절감)

# 자동 적용되는 경우:
- .claude/instructions.md (Claude CLI)
- 프로젝트 구조 (대부분 도구)
- 이전 대화 컨텍스트

# 팁: 프로젝트 지시사항을 길게 작성해도 OK
# 캐싱되므로 비용 걱정 없음

4. 불필요한 파일 제외

# Claude CLI: .claudeignore
node_modules/
.git/
dist/
build/
*.log
package-lock.json
yarn.lock

# Aider: .aiderignore
# (위와 동일)

# 효과: 컨텍스트 크기 90% 감소 → 비용 절감

5. 배치 작업

# 나쁜 예 (여러 번 요청)
"Button 컴포넌트 만들어줘"
"이제 Card 컴포넌트 만들어줘"
"Input 컴포넌트도 만들어줘"
# → 3번 API 호출

# 좋은 예 (한 번에 요청)
"다음 컴포넌트들 만들어줘:
- Button
- Card
- Input

모두 TypeScript + Tailwind 사용."
# → 1번 API 호출

비용 모니터링

# Anthropic Console
https://console.anthropic.com/settings/usage

# 확인 항목
- 일일 사용량
- 월간 누적 비용
- 토큰 사용 패턴

# 알림 설정
Settings → Usage Limits → Set Limit
# 예: 변동 초과 시 알림

비용 모니터링 가이드 →

보안 고려사항

API 키 관리

1. 환경 변수 사용

# 나쁜 예
const apiKey = "sk-ant-api03-xxx";  // 코드에 직접 하드코딩

# 좋은 예
# .env
ANTHROPIC_API_KEY=sk-ant-api03-xxx

# .env.example (Git에 커밋)
ANTHROPIC_API_KEY=your_api_key_here

# .gitignore
.env
.env.local

2. 플랫폼별 안전한 저장

# macOS: Keychain
security add-generic-password -a "anthropic" -s "api_key" -w "sk-ant-api03-xxx"

# Linux: pass
pass insert anthropic/api_key

# Windows: Credential Manager
cmdkey /generic:anthropic /user:api_key /pass:sk-ant-api03-xxx

3. 권한 제한

# .env 파일 권한 설정 (Linux/macOS)
chmod 600 .env

# 읽기/쓰기: 소유자만
# 다른 사용자: 접근 불가

.gitignore 철저히

# .gitignore (필수 항목)

# 환경 변수
.env
.env.local
.env.production

# API 키
**/secrets/
credentials.json
service-account.json

# 로그 (민감 정보 포함 가능)
*.log
logs/

# 데이터베이스
*.db
*.sqlite

# AI 도구 설정 (API 키 포함 가능)
.cursor/
.continue/
.aider.conf.yml

AI 생성 코드 검토

검토 체크리스트

• 보안 취약점
  • SQL Injection 방지
  • XSS 방지
  • CSRF 토큰
  • 입력 검증
• 에러 처리
  • try-catch 적절한지
  • 에러 메시지 유저 친화적인지
  • 민감 정보 노출 여부
• 성능
  • 불필요한 루프
  • 메모리 누수
  • 비효율적인 쿼리
• 테스트
  • 엣지 케이스 커버
  • 에러 상황 테스트

프라이버시

코드가 외부로 전송되는 도구

프라이버시 중요 시

• 로컬 LLM 사용: Continue + Ollama
• Privacy Mode: Cursor의 Privacy Mode 활성화
• 민감 코드 제외: .claudeignore에 추가
• 익명화: 실제 이름, 이메일 등 제거 후 요청

일반적인 실수 회피

실수 1: AI를 맹신

# AI가 코드 생성
# 검토 없이 바로 커밋
git add .
git commit -m "feat: Add feature"
git push

# AI가 코드 생성
# 1. 코드 검토
# 2. 테스트 실행
npm test
npm run dev  # 브라우저 확인
# 3. 문제 없으면 커밋
git add .
git commit -m "feat: Add feature"

실수 2: 모호한 요청

실수 3: Git 무시

# 나쁜 습관
# Git 없이 AI 도구 사용
# → AI가 파일 삭제하면 복구 불가!

# 좋은 습관
# 1. 항상 Git 사용
git init

# 2. AI 작업 전 커밋
git add .
git commit -m "Before AI changes"

# 3. AI 작업 후 diff 확인
git diff

# 4. 문제 있으면 되돌리기
git reset --hard HEAD

실수 4: 비용 무시

# 나쁜 습관
# Claude Opus를 모든 작업에 사용
# → 월 변동 청구

# 좋은 습관
# 작업별 모델 선택
간단한 수정 → Ollama 또는 Haiku (무료 또는 저렴)
복잡한 코드 → Sonnet ($$)
최고 품질 필요 → Opus ($$$)

# 비용 모니터링
https://console.anthropic.com/settings/usage

실수 5: API 키 노출

# 나쁜 예
# config.js (Git에 커밋됨)
export const API_KEY = "sk-ant-api03-xxx";

# 좋은 예
# .env (Git에서 제외)
ANTHROPIC_API_KEY=sk-ant-api03-xxx

# .gitignore
.env

실수 6: 단일 도구 고집

# 비효율적
# Cursor만 사용
# → 터미널 명령어 생성에 비효율적

# 효율적
# 상황에 맞게 도구 선택
IDE 작업 → Cursor
터미널 명령어 → GitHub Copilot CLI
복잡한 프로젝트 → Cline
Git 통합 → Aider

실수 7: 컨텍스트 무시

# 나쁜 예
"Button 컴포넌트 만들어줘"
# → AI가 어떤 스타일로 만들어야 할지 모름

# 좋은 예
"Button 컴포넌트 만들어줘.

프로젝트는 React + TypeScript + Tailwind 사용 중.
기존 Card 컴포넌트와 동일한 스타일 적용.
@file:components/Card.tsx 참조해서 만들어줘."

생산성 팁 10가지

1. 프로젝트 지시사항 파일 작성

# Claude CLI: .claude/instructions.md
# Cursor: .cursorrules
# Aider: .aider.conf.yml

# 한 번 작성하면 매번 반복 안 해도 됨

2. 별칭으로 단축

# ~/.zshrc
alias cl='npx claude'
alias ghcs='gh copilot suggest'
alias ghce='gh copilot explain'
alias adr='aider --model ollama/llama3.2'

3. 템플릿 프롬프트 저장

# ~/prompts/feature.txt
[기능명] 추가해줘.

요구사항:
- [기능 1]
- [기능 2]

기술 스택:
- [프레임워크]

# 사용
cat ~/prompts/feature.txt | pbcopy
# Paste to AI tool

4. 여러 도구 병행 사용

빠른 편집 → Cursor Cmd+K
프로젝트 관리 → Claude CLI
Git 통합 → Aider
터미널 → GitHub Copilot CLI

5. 자동완성 적극 활용

# Continue, Cursor의 Tab 자동완성
# 타이핑하면 자동으로 제안
# Tab으로 수락

# 많은 시간 절약!

6. 대화 히스토리 활용

# 이전 대화 참조
"이 버튼에 hover 효과 추가해줘"
# "이 버튼" = 이전에 만든 Button 컴포넌트
# AI가 컨텍스트로 이해

7. 에러 로그 직접 붙여넣기

# 에러 발생
TypeError: Cannot read property 'map' of undefined
  at UserList.tsx:15:18

# AI에게 복사-붙여넣기
"이 에러 수정해줘:
[에러 로그 붙여넣기]"

# AI가 즉시 분석 및 수정

8. 배치 작업으로 API 호출 최소화

# 나쁜 예
"Button 만들어줘"
"Card 만들어줘"
"Input 만들어줘"

# 좋은 예
"Button, Card, Input 컴포넌트 만들어줘"

9. Git 브랜치 전략

# 실험적 AI 작업은 별도 브랜치
git checkout -b ai-experiment

# AI에게 자유롭게 실험 요청

# 성공하면 merge
git checkout main
git merge ai-experiment

# 실패하면 버리기
git branch -D ai-experiment

10. 학습 모드로 활용

# AI가 코드 생성 후
"이 코드 설명해줘. 각 부분이 왜 필요한지."

# 또는
"더 나은 방법도 알려줘."

# AI를 튜터로 활용!

핵심 정리

• AI CLI 도구 모범 사례의 핵심 개념과 흐름을 정리합니다.
• 도구 선택 가이드를 단계별로 이해합니다.
• 실전 적용 시 기준과 주의점을 확인합니다.