Claude Code 설정 키트의 기능
Claude Code 설정 키트는 프로젝트 메모리, 엔지니어링 규칙, 헬퍼 에이전트, 테스트, 린트, 배포 보호 기능을 추가해 Claude Code를 보다 체계적인 개발 팀으로 만들어 줍니다. Claude Code가 더 엄격한 규율에 따라 작업하기를 원하는 사업주, 바이브 코더, IT 전문가, 개발자를 위해 설계되었습니다.
Claude Code는 세션 사이에 중요한 프로젝트 맥락을 잊거나, 일관된 보호 장치 없이 작업하거나, 문제가 있는 변경 사항을 운영 애플리케이션에 반영할 수 있습니다. 이 키트는 단일 설정 파일에서 작동하는 프로젝트 구조를 생성해 이러한 문제를 해결합니다.
새 저장소와 기존 저장소 모두에서 사용할 수 있습니다. 특히 Cloudflare Workers에 적합하며, Vercel, Node, Python과 같은 스택에도 맞게 조정됩니다.
주요 기능
- 프로젝트 메모리:
CLAUDE.md와docs/디렉터리가 현재 운영 중인 항목, 다음 작업, 결정된 사항을 보존합니다. - 작업 규칙:
.claude/rules/의 파일이 보안, 테스트, 깔끔한 코드, 일반 언어를 사용한 커뮤니케이션에 대한 기준을 정의합니다. - 7개의 헬퍼 에이전트: 더 저렴하고 빠른 모델이 검색, 빌드, 테스트, 작업 검사를 수행하고, 메인 모델은 계획과 검토에 집중할 수 있습니다.
- 위험 기반 레인: 작음, 중간, 큼으로 분류된 변경 사항에 점진적으로 더 강력한 검사가 적용됩니다.
- 푸시 보호 장치: 잘못된 대상으로의 푸시, 강제 푸시, 검사에 실패한 상태의 푸시를 차단할 수 있습니다.
- 자동 테스트 및 린트: 변경 사항이 사용자에게 도달하기 전에 검사됩니다.
- 문서 업데이트:
/update-docs명령이 다음 세션을 위해 진행 상황을 기록합니다. - 선택 기능: 공개 저장소 유출 검사, 모든 프로젝트를 위한 안전망 푸시 보호 장치, 테스트된 복원 절차가 포함된 Claude 설정 백업을 사용할 수 있습니다.
설정 키트 설치
1단계: 설정 파일 다운로드
저장소에서 SETUP-CLAUDE-STRUCTURE.md를 열고 Download raw file을 선택합니다. 처음에 추가해야 하는 파일은 이것 하나뿐입니다.
2단계: 프로젝트에 배치
SETUP-CLAUDE-STRUCTURE.md를 프로젝트의 루트 폴더에 복사합니다. 기존 저장소를 사용하거나 새 빈 폴더로 시작할 수 있습니다.
3단계: Claude Code 실행
같은 프로젝트 폴더에서 Claude Code를 열고 설정 지침을 따르도록 지시합니다.
Follow SETUP-CLAUDE-STRUCTURE.mdClaude는 짧은 질문 5개를 한 뒤 계획을 제시하고, 구조를 변경하기 전에 승인을 기다립니다. 계획을 검토한 후 준비가 되면 명확하게 확인해 주세요.
Claude Code는
.claude/폴더를 보호하므로, 해당 폴더의 개별 파일을 작성하기 전에 권한을 요청할 수 있습니다. 이러한 설정 작업을 승인하려면 Allow를 선택하세요.
설정 중 진행되는 작업
Claude는 먼저 프로젝트에 대해 질문하고 기술 스택을 파악합니다. 그런 다음 애플리케이션의 작동 방식을 변경하지 않고 기존 코드에 맞는 구조를 구축합니다.
이 설정은 구성, 문서화, 검사, 테스트를 추가하기 위한 것입니다. 애플리케이션의 동작은 변경하지 않습니다. 이미 CLAUDE.md 파일이 있다면 Claude는 기존 내용을 유지하고 적절한 위치로 옮기며, 이전 버전은 Git 기록에 남겨 둡니다.
Cloudflare에 특화된 부분이 적용되지 않는 경우 해당 부분은 건너뜁니다. 예를 들어 Node 또는 Python 프로젝트에는 Cloudflare 전용 설정 대신 감지된 스택에 맞는 검사와 규칙이 적용됩니다.
기본 사용법
새 작업 세션 시작
설정이 끝나면 프로젝트 디렉터리에서 Claude Code를 열고 완료하려는 작업을 설명합니다. 생성된 프로젝트 메모리가 현재 상태, 예정된 작업, 이전 결정에 대한 맥락을 Claude에 제공합니다.
프로젝트 문서에 나열된 다음 기능을 추가할 수 있도록 도와주세요.Claude는 프로젝트의 규칙과 위험 기반 레인을 사용해 해당 변경에 필요한 계획, 구현, 테스트, 검토의 수준을 결정합니다.
작은 변경 요청
제한적인 변경이라면 원하는 결과를 명확하게 설명하고 Claude에 확인을 요청합니다.
이 작은 UI 텍스트를 변경하고 관련 검사를 실행한 다음 변경된 내용을 보고해 주세요.작은 작업은 녹색 레인에서 처리되고, 더 크거나 위험한 변경에는 보다 광범위한 검사가 적용됩니다.
세션 사이에 진행 상황 기록
작업 세션이 끝나면 문서화 명령을 실행해 프로젝트 메모리에 최신 진행 상황을 반영합니다.
/update-docs이 명령은 다음 세션을 위해 현재 상태를 저장하므로, Claude가 처음부터 시작하는 대신 유용한 맥락을 바탕으로 작업을 시작할 수 있습니다.
안전 및 승인 규칙
이 키트는 명시적 승인과 최소 접근 원칙을 바탕으로 설계되었습니다.
- Claude는 구조를 변경하기 전에 질문합니다.
- Claude는 푸시가 애플리케이션을 배포할 수 있으므로 허락 없이 푸시하지 않습니다.
- 시크릿 이름은 문서화할 수 있지만 시크릿 값은 저장하지 않습니다.
- 규칙은 Claude가
.env및.dev.vars와 같은 민감한 파일을 열지 못하도록 차단합니다. - 테스트에는 빈 시크릿을 사용하므로 실제 서비스에 접근할 수 없습니다.
- 푸시 보호 장치는 강제 푸시, 잘못된 대상으로의 푸시, 검사 실패 시 푸시를 방지할 수 있습니다.
Claude가 보호된 설정 파일에 대한 접근 권한을 요청하면 요청된 작업을 검토하고 수행이 예상되는 작업만 승인하세요.
고급 팁
위험도에 맞게 레인별 검토 수준 사용
세 개의 레인을 가벼운 변경 관리 시스템이라고 생각해 보세요. 녹색은 작은 변경, 노란색은 중간 규모의 변경, 빨간색은 큰 변경을 의미합니다. 잠재적인 영향이 커질수록 변경을 준비 완료로 판단하기 전에 더 많은 계획 수립, 검증, 검토가 필요합니다.
프로젝트 기록을 최신 상태로 유지하세요
긴 프로젝트가 끝날 때까지 기다리지 말고, 의미 있는 작업을 마친 후 /update-docs를 사용하세요. 최신 문서는 이후 세션의 안정성을 높이고 의사 결정 과정을 명확하게 보여 줍니다.
공개 프로젝트나 진행 중인 프로젝트에는 선택적 보호 기능을 사용하세요
프로젝트가 공개되어 있다면 선택적 유출 검사를 활성화하는 것을 고려하세요. 실수로 배포될 우려가 있는 프로젝트에는 안전망 푸시 가드를 사용하세요. 백업 옵션을 사용하면 Claude 설정을 보존하고 테스트된 복원 절차도 이용할 수 있습니다.
기존 프로바이더와 기술 스택에 맞게 키트를 조정하세요
이 키트는 하나의 키로 여러 모델에 액세스할 수 있으므로 AI 애플리케이션에 OpenRouter를 권장하지만, 특정 프로바이더의 사용을 강제하지는 않습니다. 프로젝트에서 이미 다른 프로바이더를 사용하고 있다면 기존 선택이 그대로 유지됩니다.
Windows에서 푸시 가드는 Bash 스크립트로 작동합니다. WSL 또는 Git Bash를 사용하고, 필요한 설치에 관한 Claude의 안내를 따르세요.
결론
Claude Code Setup Kit는 직접 구조를 설계하지 않아도 Claude Code에 반복 가능한 프로젝트 워크플로를 제공합니다. 파일 하나를 다운로드해 프로젝트에 넣고 Claude에게 이를 따르도록 요청하세요. 승인 후에는 지속적인 프로젝트 기록, 명확한 규칙, 도우미 에이전트, 위험도에 따른 레인, 자동화된 검사, 문서 업데이트, 더욱 안전한 푸시 동작을 사용할 수 있습니다.
최신 버전은 저장소의 CHANGELOG.md를 확인하고 제공되는 릴리스를 검토하세요. 이 프로젝트는 CC BY 4.0 라이선스에 따라 제공되며, Abdo Samy를 출처로 밝히고 저장소로 연결되는 링크를 포함하면 사용, 공유, 수정이 가능합니다.