이 저장소는 개발자가 Claude를 도구가 아닌 동료처럼 활용해서 실제 업무를 더 잘 해내는 방법을 정리한 문서 모음입니다. 코드를 쓰는 일, 문서를 만드는 일, 버그를 잡는 일, 리뷰를 받는 일까지 개발자가 하루 동안 마주치는 대부분의 작업을 다룹니다.
- 프로그래밍 언어 (등급별)
- 프레임워크와 생태계
- 데이터베이스와 쿼리
- 인프라와 운영
- 개발 작업 유형
- 코드 밖의 개발 업무
- 자동화와 연동
- 스택별 활용 — Prometheus, NiFi, PostgreSQL, Oracle, Grafana
- 할 수 없는 일과 약한 일
- 어떤 창구로 Claude를 쓸 것인가
- 작업 유형별 선택 기준
- 모델 고르기 — Opus, Sonnet, Haiku
- 모델을 나눠 쓰기 — 설계는 Fable, 구현은 Opus
- 권한 모드와 안전장치
- 첫 30분에 해볼 것
- 좋은 프롬프트보다 좋은 컨텍스트
- CLAUDE.md 작성법
- 스코프 나누기 — 프로젝트, 개인, 디렉터리
- 참조로 범위 좁히기
- 긴 세션 관리하기
- 컴팩션 — 왜 필요하고 언제 해야 하는가
- 컨텍스트 오염 다루기
3. 요청을 설계하는 법
- 좋은 요청의 네 가지 요소
- 모호함을 남기지 않는 법
- 탐색 → 계획 → 구현 → 검증 루프
- 계획 모드를 쓸 때
- 깊이 생각하게 만들기
- 수정 요청을 잘 하는 법
4. 코드 작성 워크플로우
- 새 기능 만들기
- 낯선 코드베이스 파악하기
- 리팩터링하기
- 대규모 변경 나누기
- 버그 잡기
- 커밋과 PR 운영
- 병렬 작업과 서브에이전트
5. 문서화
- 코드에서 문서를 뽑아내기
- README와 아키텍처 문서
- API 문서와 스펙
- 주석은 언제 쓰고 언제 지우는가
- 체인지로그와 릴리스 노트
- 온보딩 문서 만들기
- 문서 드리프트 막기
6. 테스트와 디버깅
- 테스트를 먼저 쓰게 하기
- 의미 있는 테스트 만들기
- 실패 정보를 주는 올바른 방식
- 재현되지 않는 버그 다루기
- 성능 문제는 측정부터
- 통과했다는 보고를 검증하기
7. 코드 리뷰와 품질
- Claude에게 리뷰를 시키기
- Claude가 쓴 코드를 사람이 리뷰하기
- 보안 관점의 점검
- 스타일은 자동화에, 리뷰는 설계에
8. 자동화와 확장
- 슬래시 커맨드로 반복 작업 표준화
- 스킬로 노하우 패키징
- 훅으로 규칙 강제하기
- MCP로 외부 시스템 연결
- CI와 GitHub 연동
- 백그라운드와 스케줄 작업
9. 팀에 도입하기
- 팀 표준을 저장소에 커밋하기
- AI 생성 코드에 대한 팀 정책
- 보안과 컴플라이언스
- 비용 관리
- 단계별 도입 로드맵
- 효과 측정하기
10. 안티패턴 — 흔한 실패
- 검증 없이 통째로 받아들이기
- 한 세션에 너무 많은 일을 시키기
- "고쳐줘"만 반복하는 루프
- 컨텍스트를 안 주고 결과를 탓하기
- 지어낸 API 걸러내기
- 과한 추상화와 과한 주석
- 도구가 필요 없는 일에 도구 쓰기
- 먼저 정할 것 — 무엇이 나갈 수 있는가
- 모델 1 — 단방향 반입 (코드 반출 불가)
- 모델 2 — GitHub를 다리로 (반출 허용 시)
- 장비와 작업 방식
- 정착시키기
- 왜 터미널인가
- 설치와 첫 실행
- 세션을 여는 네 가지 방법
- 입력 문법과 단축키 —
/,@,! - 헤드리스 모드 — 파이프와 스크립트
- 여러 작업을 동시에 굴리기
- 실제 개발 환경에서 무엇이 달라지는가
13. 지원 — 스택별로 도움받는 법
- 지원의 품질을 결정하는 세 가지
- 무엇을 붙여 넣으면 답이 정확해지는가
- NiFi, Airflow, Prometheus, Grafana, Oracle, PostgreSQL
- 스택을 가로지르는 작업
- 지원 요청문 템플릿
- 받은 답을 검증하는 법
부록. 치트시트
- 상황별 프롬프트 템플릿
- CLAUDE.md 예제
- 착수 전 / PR 전 체크리스트
- 참고 링크
데이터·운영 스택(NiFi, Airflow, Prometheus, Grafana, Oracle 등)을 다루신다면 0장에서 무엇이 되는지 확인하고, 13장에서 실제로 요청하고 검증하는 방법을 보세요.
0장은 카탈로그입니다. 처음부터 끝까지 읽는 문서가 아니라 "이것도 되나?" 싶을 때 찾아보는 용도로 만들었습니다. 특히 마지막의 할 수 없는 일과 약한 일 절은 한 번 읽어 두면 사고를 줄여 줍니다.
처음이라면 1장과 2장만 읽고 바로 써보세요. 이 두 장이 전체 효과의 대부분을 만듭니다. 나머지는 필요한 순간에 해당 장을 펼쳐 보는 참고서로 쓰면 됩니다.
이미 Claude를 매일 쓰고 있다면 2장의 컨텍스트 엔지니어링과 10장의 안티패턴부터 보기를 권합니다. 대부분의 불만은 이 두 장에서 해결됩니다.
각 문서 맨 아래에는 그 문서에서 쓰인 용어를 풀어 쓴 용어집이 붙어 있습니다. 모르는 단어가 나오면 문서를 끝까지 스크롤해 보세요.
첫째, 프로젝트 최상위에 CLAUDE.md 파일을 만들어 빌드 명령, 테스트 명령, 코딩 규칙 세 가지만 적어 두세요. 이것만으로 Claude가 엉뚱한 명령어를 시도하는 일이 사라집니다.
둘째, 무언가를 시킬 때 "완료 조건"을 한 줄 덧붙이세요. "로그인 기능 만들어줘" 대신 "로그인 기능을 만들고, npm test가 통과하면 완료야"라고 하는 것만으로 결과물의 완성도가 달라집니다.
셋째, 결과를 그대로 받아들이지 말고 반드시 직접 확인하세요. 테스트를 돌리고, diff를 읽고, 실제로 실행해 보세요. 이 습관 하나가 나머지 아홉 가지 조언보다 중요합니다.
| 용어 | 설명 |
|---|---|
| Claude | Anthropic이 만든 AI 어시스턴트. 이 문서에서는 주로 개발 작업에 쓰는 맥락으로 등장합니다. |
| Claude Code | 터미널, IDE, 웹, 데스크톱 앱에서 쓰는 Claude 기반 코딩 도구. 파일을 직접 읽고 고치고 명령을 실행할 수 있습니다. |
| CLAUDE.md | 프로젝트에 대한 정보를 Claude에게 미리 알려주는 파일. 저장소 최상위에 두면 세션마다 자동으로 읽힙니다. |
| 컨텍스트(context) | Claude가 답을 만들 때 참고하는 정보 전체. 대화 내역, 읽은 파일, 시스템 지시문 등이 모두 포함됩니다. |
| 프롬프트(prompt) | Claude에게 보내는 요청 문장. |
| 세션(session) | 하나의 연속된 대화. 세션 안에서는 앞의 맥락이 유지됩니다. |
| diff | 변경 전후의 차이를 보여주는 형식. 어떤 줄이 지워지고 어떤 줄이 추가됐는지 보여줍니다. |
| PR (Pull Request) | 코드 변경을 본 저장소에 반영해 달라고 요청하는 단위. 리뷰가 이 단위로 이루어집니다. |