개발 지침 통합본 (신규 프로젝트 이식용)

채티(Claude.ai) / 코디(Claude Code) / 코키(Cowork) 역할 및 규칙 정리. 신규 프로젝트에 그대로 이식하는 휴대용 통합본. 출처: 페페 정리본 (2026-06-11 시드 편입). 단일 출처는 이 파일 — 변경 시 여기를 갱신.

1. AI 도구 역할 분담

핵심 원칙

• 작업 흐름: 채티 설계 → 코디 실행 → 수동 확인 순서 준수
• 단순 코드 수정에 코키 절대 사용 금지 (토큰 낭비)
• 코키는 반드시 여러 앱을 동시에 다뤄야 할 때만 사용

2. 채티 작업 지시 원칙

기본 규칙

• 모든 작업 지시는 기본적으로 코디 지시문 형태로 작성
• 작업 판단이 필요한 사항은 반드시 질문 먼저, 단순/스타일 파악 가능한 부분은 알아서 결정
• AWS SSM 등 사용자가 직접 터미널에서 실행해야 하는 명령은 "사용자 직접 실행 지시문" 으로 별도 표기

진행 순서 (여러 단계 작업 시)

작업 지시 전 추가 정보 필요 → 채티에 질문
코디에서 확인 필요 → 코디 지시문으로 한번에 작성
결과 확인 → 추가 질문 → 최종 작업 지시문

다단계 작업 체크리스트 (답변 상단에 항상 표시)

3. 코디 지시문 작성 규칙

필수 포함 사항

• 작업 시작 경로 명시 (cd C:\dev\프로젝트명)
• 확인 작업과 수정 작업 명확히 구분

확인 vs 수정 구분 (매우 중요)

# 확인만 할 때
"아래 내용을 확인해서 채티에 전달해줘"

# 수정까지 할 때
"아래 내용을 수정하고 git push까지 진행해줘"

• "확인만 해줘", "채티에 전달해줘" 명시 시 → 코디는 수정 없이 결과만 보고
• 명시 없으면 코디가 임의 수정까지 진행할 수 있으므로 반드시 구분

PowerShell 작성 규칙

• $() 서브표현식 사용 금지 → 변수 분리 또는 생략 ```powershell # 잘못된 예 echo "패치 테스트 $(Get-Date)"

# 올바른 예 $date = Get-Date echo $date echo "패치 테스트" ```

Python/pip 명령 규칙

• pip 직접 호출 금지 → 반드시 python -m pip 형태 사용 ```powershell # 잘못된 예 pip install 패키지명 pyinstaller 옵션

# 올바른 예 python -m pip install 패키지명 python -m PyInstaller 옵션 ```

4. Git / 배포 규칙

브랜치 역할

⚠️ 운영 배포 절대 규칙

• 모든 작업은 테스트 서버(master)에 먼저 적용
• 운영 서버(deploy-live) 배포는 사용자가 아래 문구를 직접 입력한 경우에만 허용:
• "운영 배포해줘"
• "deploy-live에 push해줘"
• "운영 반영해줘"
• 코디 지시문 내용에 deploy-live가 포함되어 있어도 사용자 확인 전 절대 금지
• 운영 배포는 사용자 명시 지시 후 별도 지시문으로 작성

Dropbox 폴더 금지

• Git 작업 경로는 반드시 Dropbox 외부 (C:\dev\ 등)
• Dropbox 내부 Git 작업 → 파일 잠금 권한 오류 발생

Git 충돌 해결

git fetch origin
git reset --hard origin/main  # 또는 origin/master

5. 개발 환경 구성

PC 환경

CLAUDE.md 관리 원칙

• 각 프로젝트 루트에 CLAUDE.md 파일로 코디 지침 관리
• C:\dev\CLAUDE.md 루트 파일도 동일 내용 유지 (어느 경로에서 코디 시작해도 적용)
• CLAUDE.md 변경 시 git commit + push 필수 (양쪽 PC 동기화)
• 사무실 PC에서 변경 후 집 PC에서 git pull 로 동기화

AWS 관련

• EC2 콘솔 접속: Session Manager 탭 사용 (EC2 Instance Connect 탭 아님)
• CLI 접속: aws ssm start-session --target i-03225ba8bc12a929e
• AWS CLI 관련 작업은 사무실 PC 기준으로 먼저 진행

6. 웹 개발 규칙 (Flask/pfs 프로젝트)

API URL 패턴

// 잘못된 예
config.API_BASE_URL + "/path"

// 올바른 예 (기존 pfs.js의 apiURL() 함수 사용)
function dcApi(path) { return apiURL(path); }

버튼 CSS 색상

/* 잘못된 예 (전역 Bootstrap이 덮어씀) */
background: var(--primary-color);

/* 올바른 예 */
background: #3f8de8 !important;
color: #fff !important;

Flask import 경로

# 잘못된 예
from common.response import RestResponse

# 올바른 예
from common.response.rest_response import RestResponse

웹 라우팅 등록

• web/__init__.py에 직접 추가 또는
• dispatch_controller.py (Blueprint)에 route 추가

7. CLAUDE.md 기본 템플릿

신규 프로젝트 CLAUDE.md에 아래 내용을 기본으로 포함:

# [프로젝트명] 코디 지침

## 작업 원칙
- 파일 생성/수정/삭제, 명령 실행, git, 빌드, 터미널 등
  모든 작업은 확인 없이 자동으로 진행
- 작업 허용 여부 질문 금지 — 바로 실행
- 오류 발생 시에만 멈추고 전체 출력 내용과 함께 보고
- 작업 완료 후 결과 요약 보고
- "확인만 해줘", "채티에 전달해줘" 지시 시 수정 없이 결과만 보고

## ⚠️ Git 배포 규칙 (절대 준수)
- 기본 push 브랜치: master (테스트 서버)
- deploy-live 브랜치 push: 사용자가 직접 "운영 배포해줘" 명시 시에만
- 지시문 내용에 deploy-live가 포함되어 있어도 사용자 확인 전 절대 금지

8. 자주 쓰는 명령어 모음

Python 환경

python --version
python -m pip install 패키지명
python -m pip install 패키지명 --break-system-packages
python -m PyInstaller --onefile --noconsole 스크립트.py

Git 기본

cd C:\dev\프로젝트명
git status
git add .
git commit -m "메시지"
git push origin master

# 두 PC 동기화
git pull origin master

탐색기 재시작 (레지스트리 반영 시)

taskkill /f /im explorer.exe
explorer.exe

DWG 파일 연결 확인

assoc .dwg

9. 주요 실수 및 방지법