From 624e5fd7d995a0113f3a91f1d1eeab776828f764 Mon Sep 17 00:00:00 2001 From: joungmin Date: Fri, 27 Feb 2026 19:25:28 +0900 Subject: [PATCH] docs: add detailed workflow examples and role-specific prompt patterns - Add end-to-end issue-to-deploy workflow with Claude Code prompts - Add daily standup assistant workflow - Add knowledge accumulation workflow with Obsidian - Add onboarding guide for new team members - Add troubleshooting guide for common scenarios Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 259 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 259 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index cb322df..f3a9018 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -408,6 +408,142 @@ claude -p "현재 브랜치의 git diff를 분석해서 PR 본문 초안을 한 "Redmine 이슈 #342 상태를 완료로 변경하고 실제 소요 시간을 기록해줘." ``` +### 워크플로우 1: 이슈 → 개발 → 배포 전체 사이클 (상세) + +``` +[PM] Redmine 이슈 생성 + "API 로그인 기능에 JWT refresh token 추가 (RM-342)" + ↓ +[개발자] Claude Code에 작업 지시 + "RM-342 이슈를 Redmine에서 읽고 구현 시작해줘" + → Claude: 이슈 로드, Gitea 브랜치 생성, 구현 계획 제시 + ↓ +[개발자] 코드 구현 + "auth_service.py에 refresh token 로직 추가해줘. 기존 패턴 유지." + → Claude: 코드 생성 + 단위 테스트 함께 생성 + ↓ +[개발자] PR 생성 + "현재 브랜치로 PR 만들어줘. Redmine RM-342 연결, 리뷰어 tech_lead 지정." + → Claude: Gitea PR 생성 → Jenkins CI 자동 트리거 + ↓ +[QA] 커버리지 검토 + "RM-342 PR의 테스트 커버리지 확인하고, 추가 테스트 시나리오 제안해줘" + → Claude: 커버리지 분석, 누락 케이스 제시 + ↓ +[QA] 버그 발견 시 + "refresh token 만료 후 재발급 시 500 에러 발생. Redmine 버그 이슈 만들어줘." + → Claude: Redmine 버그 이슈 생성 (RM-343) + ↓ +[개발자] 버그 수정 + "Jenkins 빌드 로그 분석해서 RM-343 원인 찾아줘" + ↓ +[PM] 완료 처리 + "RM-342를 완료로 변경하고 Obsidian 스프린트 리포트에 추가해줘" +``` + +### 워크플로우 2: 일일 스탠드업 보조 +```bash +claude -p " +Redmine에서 내(assigned_to=me) 이슈 중 +어제 업데이트된 것과 오늘 마감인 것을 가져오고, +Jenkins에서 어제 실패한 빌드 목록을 가져와서 +스탠드업용 요약을 만들어줘: +- 어제 한 일 +- 오늘 할 일 +- 블로커 +" +``` + +### 워크플로우 3: 지식 축적 (Obsidian) +```bash +claude -p " +방금 JWT refresh token 구현을 완료했어. +핵심 결정사항과 트레이드오프를 Obsidian의 +TIL/2026-03-01-jwt-refresh-implementation.md 에 정리해줘. +다음 개발자를 위한 '왜 이렇게 구현했는가' 포함. +" +``` + +--- + +## 팁 & 트러블슈팅 + +### 설정 팁 + +**팁 1: 환경변수 분리** +```bash +# 팀 공유 .env.example (Git 커밋) +REDMINE_URL=https://redmine.cloud-handson.com +REDMINE_API_KEY= +JENKINS_URL=https://jenkins.cloud-handson.com + +# 개인 .env (Git 제외) +REDMINE_API_KEY=실제키값 +``` + +**팁 2: MCP 서버 디버깅** +```bash +# MCP 연결 상태 확인 +claude mcp list + +# 특정 MCP 정보 확인 +claude mcp get redmine + +# 상세 로그로 실행 +claude --verbose +``` + +**팁 3: 컨텍스트 윈도우 최적화** + +MCP 서버가 많아지면 컨텍스트가 넘칠 수 있다. +``` +MCP 사용 지침: +- Redmine 이슈 조회 시 필요한 필드만 요청 (전체 본문 X) +- Jenkins 로그는 최근 100줄만 +- Gitea 파일 조회는 필요한 파일만 +``` + +**팁 4: 역할별 Claude Code 세션 분리** +```bash +# 역할별 디렉터리에서 실행하면 다른 CLAUDE.md 적용 가능 +/Users/joungmin/workspaces/ + {프로젝트-frontend}/ # 프론트엔드용 CLAUDE.md + {프로젝트-backend}/ # 백엔드용 CLAUDE.md +``` + +**팁 5: Sub-agent 활용 (병렬 작업)** +```bash +claude -p " +다음 3가지를 동시에 처리해줘: +1. Redmine 이슈 #342 진행 중으로 변경 +2. Gitea에 feature/RM-342 브랜치 생성 +3. Obsidian Daily/2026-03-01.md에 작업 시작 기록 +" +``` + +### 트러블슈팅 + +| 문제 | 원인 | 해결 | +|------|------|------| +| `claude: command not found` | PATH 미설정 | `export PATH="$(npm config get prefix)/bin:$PATH"` | +| MCP 서버 연결 실패 | 환경변수 미설정 | `.env` 확인, `source .env` | +| 컨텍스트 초과 오류 | MCP 데이터 과다 | 조회 필드/범위 제한 | +| Redmine 인증 실패 | API Key 만료 | Redmine에서 키 재발급 | +| Jenkins 403 | CSRF 설정 | Crumb 토큰 추가 필요 | +| Gitea SSL 오류 | 자체 서명 인증서 | `PYTHONHTTPSVERIFY=0` 또는 cert 등록 | + +### Jenkins CSRF (Crumb) 처리 +```python +def get_crumb(): + r = requests.get(f"{JENKINS_URL}/crumbIssuer/api/json", headers=auth()) + data = r.json() + return {data["crumbRequestField"]: data["crumb"]} + +# POST 요청 시 crumb 헤더 추가 +headers = {**auth(), **get_crumb()} +requests.post(url, headers=headers, ...) +``` + --- ## 금기 사항 (AI 포함 모든 기여자 준수) @@ -481,6 +617,126 @@ draft-pr: --- +## Claude Code 활용 극대화 전략 + +> Claude Code를 단순 질문 도구가 아니라 **여러 명의 유능한 직원**처럼 구조화하여 운용하는 방법입니다. + +### 1. 병렬 멀티 세션 운용 + +터미널 창을 여러 개 띄워 각기 다른 도메인을 동시에 처리합니다. + +``` +터미널 1: feature/RM-342 구현 (auth 도메인) +터미널 2: feature/RM-338 버그 수정 (payment 도메인) +터미널 3: 문서 작성 / Obsidian 정리 +터미널 4: 테스트 커버리지 보완 +터미널 5: 코드 리뷰 초안 생성 +``` + +완료 알림을 설정하면 화면을 계속 볼 필요 없이 다른 업무에 집중할 수 있습니다. + +```bash +# macOS 완료 알림 (CLAUDE.md 또는 ~/.zshrc에 추가) +# Claude Code 작업 끝날 때 소리 알림 +alias claude-notify='claude "$@" && afplay /System/Library/Sounds/Glass.aiff' +``` + +### 2. Plan Mode 우선 원칙 + +코드를 바로 짜게 하지 말고, **먼저 계획을 세우고 검토**한 뒤 구현합니다. + +```bash +# Step 1: 계획 수립 (Plan Mode) +"RM-342 이슈를 읽고 구현 계획만 세워줘. 코드는 아직 작성하지 마." + +# Step 2: 계획 비판적 검토 (다른 세션 또는 이어서) +"방금 세운 계획의 문제점과 리스크를 비판적으로 검토해줘. + 보안 취약점, 엣지 케이스, 성능 이슈 중심으로." + +# Step 3: 검토 결과 반영 후 구현 +"검토 결과를 반영해서 이제 구현해줘." +``` + +### 3. 자기 검증 (Self-Verification) + +작업 완료 후 Claude가 **직접 결과를 실행하거나 확인**하도록 지시합니다. +이 단계를 거치면 결과물 품질이 2~3배 향상됩니다. + +```bash +# 구현 후 자기 검증 요청 +"구현이 끝나면 직접 테스트를 실행하고 통과 여부를 확인해줘." +"API 엔드포인트를 만들었으면 curl로 직접 호출해서 응답을 확인해줘." +"UI를 수정했으면 브라우저에서 직접 열어서 렌더링을 확인해줘." +``` + +### 4. 복리 학습 메모장 운영 + +실수가 발생하면 즉시 이 파일(CLAUDE.md)을 업데이트합니다. +같은 실수가 반복되지 않도록 **누적 학습** 구조를 만듭니다. + +```bash +# 실수 발생 시 즉시 기록 +"방금 발생한 실수를 CLAUDE.md의 '자주 하는 실수' 항목에 추가해줘." +``` + +**자주 하는 실수 목록** ← 실수 발생 시 여기에 추가 +- (발생 시 항목 추가) + +### 5. SDD (Specification Driven Development) + +코드 작성 전 **설계서를 먼저 작성**합니다. 명확한 기준이 있으면 수십 번의 수정을 방지합니다. + +```bash +# 구현 전 설계서 작성 +"RM-342 이슈를 바탕으로 구현 전에 설계서를 먼저 작성해줘. + 포함 항목: API 명세, 데이터 모델, 엣지 케이스, 수락 기준. + Obsidian Requirements/RM-342-spec.md에 저장해줘." + +# 설계서 기반 구현 +"Obsidian Requirements/RM-342-spec.md의 설계서를 읽고 구현해줘." +``` + +### 6. 세션 인수인계 (컨텍스트 이어받기) + +새 세션을 시작하면 이전 대화를 잊기 때문에, **진행 상황을 요약 파일로 저장**합니다. + +```bash +# 세션 종료 전 저장 +"지금까지 작업한 내용, 결정사항, 미완료 항목을 요약해서 + /Users/joungmin/workspaces/{프로젝트}/SESSION_HANDOFF.md에 저장해줘." + +# 새 세션 시작 시 +"SESSION_HANDOFF.md를 읽고 이전 작업을 이어서 진행해줘." +``` + +### 7. 도메인별 Claude 분리 + +큰 프로젝트는 **영역별로 별도 세션**을 운용하여 간섭과 혼선을 줄입니다. + +``` +/Users/joungmin/workspaces/{프로젝트}/ +├── backend/auth/ → 터미널 1 전담 (인증/인가) +├── backend/payment/ → 터미널 2 전담 (결제) +├── backend/admin/ → 터미널 3 전담 (관리자) +└── frontend/ → 터미널 4 전담 (UI) +``` + +각 도메인 폴더에 별도 `CLAUDE.md`를 두면 도메인 특화 지침을 적용할 수 있습니다. + +### 8. 단축 명령어 / 스킬 등록 + +자주 반복하는 작업 순서를 **명령어 하나**로 저장합니다. + +```bash +# ~/.zshrc 또는 Makefile에 등록 +alias cc-start='claude -p "SESSION_HANDOFF.md를 읽고 오늘 할 작업을 정리해줘"' +alias cc-end='claude -p "오늘 작업 내용을 SESSION_HANDOFF.md에 업데이트해줘"' +alias cc-review='claude -p "현재 브랜치 변경사항을 보안·성능·컨벤션 관점으로 리뷰해줘"' +alias cc-standup='claude -p "Redmine 내 이슈와 Jenkins 빌드 상태를 가져와서 스탠드업 요약을 만들어줘"' +``` + +--- + ## AI 작업 지침 > AI가 이 저장소에서 코드를 생성하거나 수정할 때 반드시 따라야 할 규칙입니다. @@ -490,6 +746,9 @@ draft-pr: 3. **테스트 동반 작성**: 새 함수/로직 작성 시 대응하는 단위 테스트 함께 제안 4. **불확실 시 질문**: 요구사항이 모호하면 임의로 결정하지 말고 반드시 확인 요청 5. **보안 우선**: 인증/인가 로직은 임의로 우회하거나 단순화하지 말 것 +6. **Plan Mode 우선**: 복잡한 작업은 계획 수립 → 비판적 검토 → 구현 순서로 진행 +7. **자기 검증**: 구현 완료 후 직접 테스트 실행하여 결과 확인 +8. **실수 기록**: 오류 발생 시 CLAUDE.md의 '자주 하는 실수 목록' 즉시 업데이트 ---