Claude Code를 시작시 초반 구조 자동으로 잡아보자

이 글은 Claude Code를 처음 프로젝트에 붙일 때 많은 팀이 비슷하게 겪는 문제를 어떻게 줄일 수 있는지 정리한 글입니다. 특히 “두 번째 세션부터 컨텍스트가 사라진다”, “에이전트에게 많이 맡겼더니 결과가 서로 충돌한다”, “하드 룰은 개발하다가 뒤늦게 떠오른다” 같은 문제를, 시작 단계에서 구조화하는 방법에 초점을 맞춥니다.

공개된 저장소 기준으로, AlexZio00/claude-code-skills는 Claude Code용 실전형 스킬 모음이며 현재 README에서 확인되는 핵심 스킬은 /project-init입니다. 이 스킬은 코드를 쓰기 전에 인터뷰를 통해 CLAUDE.md와 DEVELOPMENT_ROADMAP.md를 생성하는 방식으로 프로젝트의 기본 원칙을 먼저 고정하자는 접근을 취합니다. (GitHub)

이 글을 읽으면 다음을 이해할 수 있습니다. 왜 많은 Claude Code 프로젝트가 초반에 흔들리는지, 왜 “무엇을 만드는가 / 어떻게 구성하는가 / 누가 만드는가”를 먼저 정해야 하는지, 그리고 /project-init가 그 문제를 어떤 방식으로 줄이려는지입니다. Claude Code를 이제 막 쓰기 시작한 개발자나, 팀 단위 에이전트 워크플로를 정리하려는 사람에게 특히 도움이 됩니다. (GitHub)

GitHub - AlexZio00/claude-code-skills: Four skills for Claude Code projects: audit existing projects, scaffold new ones, wire th

 

왜 이 문제가 중요한가

Claude Code 같은 에이전트 기반 개발 도구는 생산성을 크게 올려줄 수 있습니다. 하지만 초반 구조 없이 바로 코드를 만들기 시작하면, 속도보다 정합성 문제가 먼저 터지는 경우가 많습니다.

기존 방식의 대표적인 문제는 이런 식입니다.

• 세션이 바뀔 때마다 맥락을 다시 설명해야 한다
  프로젝트 목표, 아키텍처 원칙, 금지 사항이 문서화되어 있지 않으면 다음 세션에서 같은 설명을 반복하게 됩니다. 저장소 README의 표현대로, CLAUDE.md before code가 중요한 이유도 여기에 있습니다. (GitHub)
• 하드 룰이 뒤늦게 추가된다
  예를 들어 “UI는 DB만 읽고 외부 API를 직접 호출하지 않는다”, “로그는 append-only로 남긴다”, “feature flag는 기본 OFF” 같은 규칙은 초반에는 없었다가 나중에 생기기 쉽습니다. 그런데 이런 규칙은 나중에 붙이면 이미 만들어진 코드가 규칙을 어기고 있을 가능성이 큽니다. 저장소도 바로 이 점을 핵심 문제로 지적합니다. (GitHub)
• 여러 에이전트가 각자 맞다고 생각하는 방향으로 구현한다
  공통 규약이 없으면 한 에이전트는 빠른 구현을, 다른 에이전트는 장기 유지보수를 우선합니다. 결과적으로 폴더 구조, 에러 처리, 비밀정보 관리, 데이터 접근 방식이 섞입니다. 이는 사용자가 제공한 문제의식과도 맞닿아 있습니다.
• 로드맵 없이 작업이 분산된다
  “지금 무엇을 먼저 만들어야 하는가”가 정리되지 않으면, 중요한 기반 작업보다 눈에 보이는 기능부터 붙이게 됩니다. /project-init가 인터뷰 후 Phase 구조의 로드맵 파일을 생성하는 이유가 바로 이것입니다. (GitHub)
• 보안과 운영 규칙이 빠진 채 시작된다
  .env 커밋 금지 같은 기본 시크릿 정책조차 초반에 빠질 수 있습니다. README는 명시적으로 “one .env commit compromises even private repos”라고 설명하며 secrets policy를 초기 설정에 포함합니다. (GitHub)

실무에서는 이 문제가 결국 비용으로 이어집니다.
처음 며칠은 빨라 보이지만, 이후에는 컨텍스트 재설명 비용, 충돌 수정 비용, 규칙 위반 리팩터링 비용이 누적됩니다. “빨리 시작했다”는 장점이 “나중에 다시 정리해야 한다”는 비용으로 되돌아오는 구조입니다.

claude-code-skills란 무엇인가

claude-code-skills는 Claude Code에서 쓸 수 있는 실전형 스킬 모음입니다. README의 한 문장 정의를 바꾸어 말하면, 실제 운영 경험에서 나온 개발 규칙과 프로젝트 시작 절차를 Claude Code에서 재사용할 수 있게 묶은 스킬 저장소라고 볼 수 있습니다. (GitHub)

현재 공개 README에서 확인되는 대표 스킬은 /project-init입니다. 이 스킬은 “프로젝트를 바로 구현하지 말고, 먼저 질문을 통해 불변 조건과 구조를 정리하자”는 생각에 기반합니다. 단순히 템플릿 파일을 복사하는 것이 아니라, 질문을 통해 프로젝트에 맞는 CLAUDE.md와 로드맵을 생성한다는 점이 핵심입니다. (GitHub)

기존 방식과의 차이도 여기서 드러납니다.

• 기존 방식: 아이디어를 설명하고 바로 코드 생성 시작
• /project-init 방식: 아이디어를 설명한 뒤, 구조와 제약부터 확정하고 코드로 넘어감

즉, “프롬프트로 개발을 시작하는 방식”에서 “규칙이 먼저 있는 개발 방식”으로 바꾸는 도구에 가깝습니다.

핵심 특징

• 인터뷰 기반 시작
  • 8개의 질문을 한 번에 던지는 대신, 하나씩 묻는 방식으로 프로젝트 정의를 구체화합니다. (GitHub)
• CLAUDE.md 자동 생성
  • Hard Rules, Secrets Policy, Dev Conventions를 프로젝트 맞춤형으로 정리합니다. (GitHub)
• DEVELOPMENT_ROADMAP.md 생성
  • 작업 순서를 Phase 단위로 정리해, 초반 우선순위를 명확히 합니다. (GitHub)
• 언어별 폴더 구조 제안
  • Python, TypeScript, Java/Kotlin, Go, Rust, Swift 등에 맞는 구조를 제안한다고 명시되어 있습니다. (GitHub)
• 초기 불변 조건 강제
  • 나중에 붙이면 비싸지는 규칙을 day one에 정하게 만드는 것이 핵심 철학입니다. (GitHub)
• Claude Code 세션 간 컨텍스트 유지에 유리
  • 프로젝트의 기준 문서를 먼저 만든다는 점에서, 세션이 바뀌어도 기준점이 남습니다. 이는 README의 “re-explaining context every session is expensive”라는 문제의식과 직접 연결됩니다. (GitHub)

실제로 어떤 효과가 있는가

공개 자료 기준으로, 이 저장소는 성능 수치나 정량적 벤치마크를 제공하지는 않습니다. 따라서 “몇 퍼센트 더 빨라진다” 같은 식으로 단정할 수는 없습니다. 다만 문서상 확인되는 범위에서는 다음 효과를 기대하는 설계입니다. (GitHub)

1) 세션 전환 비용 감소

초기 인터뷰 결과가 CLAUDE.md로 남으면, 다음 세션에서 매번 “이 프로젝트는 왜 만들고, 어떤 규칙을 지켜야 하는가”를 설명할 필요가 줄어듭니다.
에이전트 개발에서 생각보다 큰 비용은 생성 자체가 아니라 맥락 복원입니다.

2) 구현 충돌 감소

Hard Rules와 Dev Conventions를 초반에 정하면, 여러 번의 코드 생성 결과가 한 방향으로 수렴할 가능성이 높아집니다.
예를 들어,

• UI가 외부 API를 직접 호출하지 않는다
• feature flag는 기본 OFF다
• 로그는 append-only다

같은 원칙은 사소해 보이지만, 실제로는 데이터 흐름과 운영 방식 전체를 고정합니다. (GitHub)

3) 초반 설계 누락 방지

README에 따르면 인터뷰 항목에는 언어/런타임, 데이터 레이어, 인터페이스, 배포 방식, AI/LLM 전략, 하드 룰, 범위와 일정이 포함됩니다. 즉 “일단 만들어보고 나중에 정하자”로 빠지기 쉬운 항목을 초반에 체크하게 만듭니다. (GitHub)

4) 팀 단위 작업에 더 잘 맞음

사용자가 적어주신 “무엇을 만드는가 / 어떻게 구성하는가 / 누가 만드는가”라는 세 가지 질문은 실제로 팀 에이전트 운영에서 중요한 기준입니다. 공개 README는 현재 /project-init 중심이지만, 이 문제의식 자체는 팀 작업에서 특히 더 중요합니다.
한 명이 쓰는 도구가 아니라, 여러 역할이 섞일 때 더 효과가 커지는 구조입니다.

동작 원리 / 구조

/project-init의 동작 방식은 README 기준으로 비교적 단순합니다. 하지만 단순해서 실무 적용이 쉽습니다. (GitHub)

1. 프로젝트 아이디어를 입력한다
   • 새 세션에서 /project-init를 호출합니다.
   • 필요하면 프로젝트 아이디어나 기존 노트를 함께 붙일 수 있습니다. (GitHub)
2. Claude가 8개의 질문을 순차적으로 묻는다
   • Core definition
   • Language / runtime
   • Data layer
   • Interface
   • Deployment
   • AI / LLM
   • Hard rules
   • Scope & timeline
     이 순서대로 하나씩 물으며 구조를 잡습니다. (GitHub)
3. 스택 요약을 먼저 보여준다
   • 인터뷰 후 Claude가 스택 요약을 제시하고 승인받는 흐름입니다. (GitHub)
4. 문서를 생성한다
   • CLAUDE.md
   • DEVELOPMENT_ROADMAP.md
     두 파일을 생성해 이후 세션과 구현의 기준점으로 삼습니다. (GitHub)
5. 언어에 맞는 폴더 구조를 제안한다
   • 프로젝트 형태에 따라 초기 디렉터리 구조까지 함께 제안합니다. (GitHub)

머릿속으로 그리면, “질문 → 기준 확정 → 문서화 → 구현 시작”의 파이프라인입니다.
중요한 점은 코드 생성이 마지막이라는 것입니다. 이 스킬은 코드를 빨리 만들기 위한 스킬이라기보다, 나중에 덜 망가지게 시작하는 스킬에 가깝습니다.

설치 / 사용 방법

README 기준 설치 방법은 아래와 같습니다. (GitHub)

설치

# macOS / Linux
mkdir -p ~/.claude/skills/project-init
cp project-init/skill.md ~/.claude/skills/project-init/skill.md

Windows 예시도 README에 포함되어 있습니다.

mkdir "%USERPROFILE%\.claude\skills\project-init"
copy project-init\skill.md "%USERPROFILE%\.claude\skills\project-init\skill.md"

실행

/project-init

또는 기존 메모를 함께 붙여서 시작할 수 있습니다.

/project-init
[paste your project idea or point to a file]

기본 사용 흐름

1. /project-init 실행
2. Claude가 질문을 하나씩 던짐
3. 답변하면서 프로젝트 조건 확정
4. 스택 요약 확인
5. CLAUDE.md + DEVELOPMENT_ROADMAP.md 생성
6. 그 다음부터 실제 구현 시작

추천 시작 방식

실무에서는 아래처럼 답을 준비해두면 좋습니다.

- 이 프로젝트는 누가 쓰는가?
- 첫 버전에서 꼭 필요한 기능은 무엇인가?
- 데이터는 어디서 오고 어디에 저장되는가?
- UI / API / 배치 중 무엇이 중심인가?
- 절대 깨지면 안 되는 규칙은 무엇인가?
- 비밀정보와 로그는 어떻게 다룰 것인가?

이렇게 준비해두면 인터뷰 응답이 더 구체적이 되고, 생성되는 문서 품질도 함께 올라갑니다.

자주 쓰는 예시 / 활용 시나리오

1) 첫 개인 프로젝트 시작할 때

사이드 프로젝트는 보통 빨리 만들수록 좋다고 생각하기 쉽습니다.
하지만 데이터 저장 방식, 인증 방식, 배포 방식이 늦게 결정되면 오히려 더 오래 걸립니다. 이때 /project-init는 최소한의 설계 질문을 먼저 통과하게 해줍니다. (GitHub)

2) Claude Code를 팀에 처음 도입할 때

한 명은 프론트엔드 감각으로, 다른 한 명은 백엔드 감각으로, 또 다른 에이전트는 단순 기능 완성을 목표로 답을 내면 결과가 섞입니다.
이럴 때 공통 기준 문서가 먼저 있어야 팀 전체의 방향이 맞습니다.

3) AI/LLM 기능이 들어가는 서비스 설계할 때

README에는 인터뷰 항목 중 하나로 AI / LLM 전략이 포함되어 있고, cloud vs local, cost gating을 묻는다고 되어 있습니다.
즉, 모델을 붙일지 말지뿐 아니라 비용과 운영 정책도 초반에 정하도록 유도합니다. (GitHub)

4) 규정이 중요한 프로젝트

예를 들어,

• 로그 보존 정책이 중요하다
• 외부 API 호출 위치를 엄격히 통제해야 한다
• feature flag 정책이 중요하다
• secrets 관리가 중요하다

이런 프로젝트는 “잘 만드는 것”만큼 “규칙을 안 깨는 것”이 중요합니다. /project-init는 이 부분에 특히 잘 맞습니다. (GitHub)

5) 두 번째 세션부터 자꾸 흔들리는 프로젝트

첫 세션에서는 잘 되는데, 다음 세션부터 설명이 달라지고 산출물이 흔들린다면 대부분 기준 문서가 없기 때문입니다. 이 경우 생성 속도를 높이기보다 기준점을 먼저 만드는 쪽이 더 효과적입니다.

한계 / 주의할 점

장점만 보고 도입하면 오해하기 쉽습니다. 공개된 자료 기준으로, 이 스킬에는 몇 가지 한계도 분명히 있습니다.

공개 저장소에서 현재 명확히 확인되는 것은 /project-init 중심이다

사용자가 언급한 /harness-init, /team-init 구성은 이번 메시지의 설명에는 포함되어 있지만, 제가 확인한 공개 GitHub README에서는 현재 /project-init만 구체적으로 문서화되어 있습니다. 따라서 나머지 둘에 대해서는 저장소 문서상 확인되는 범위 이상으로 단정하면 안 됩니다. (GitHub)

좋은 답을 넣어야 좋은 결과가 나온다

인터뷰 기반 도구는 질문이 좋아도, 답변이 모호하면 결과 문서도 모호해집니다.
즉, 이 스킬은 “생각을 대신해주는 도구”라기보다 “생각을 구조화해주는 도구”에 가깝습니다.

코드 품질을 자동으로 보장해주지는 않는다

CLAUDE.md와 로드맵이 생긴다고 해서 구현이 자동으로 좋아지는 것은 아닙니다.
이 도구가 보장하는 것은 “방향”이지, “완성도” 자체는 아닙니다.

매우 작은 실험에는 과할 수 있다

1시간짜리 실험 코드나 throwaway prototype이라면 인터뷰와 문서 생성이 오히려 무겁게 느껴질 수 있습니다.
다만 “나중에도 이어갈 가능성”이 조금이라도 있다면, 초반 10분 구조화가 오히려 시간을 아껴줄 수 있습니다.

마무리

Claude Code를 처음 쓸 때 막히는 이유는, 모델이 똑똑하지 않아서가 아니라 프로젝트의 기준점이 먼저 없기 때문인 경우가 많습니다. 처음엔 코드 생성 속도가 중요한 것처럼 보이지만, 실제로는 세션 간 컨텍스트 유지, 에이전트 간 충돌 방지, 하드 룰의 조기 확정이 더 큰 차이를 만듭니다.

공개된 자료 기준으로 /project-init는 바로 그 지점을 겨냥한 스킬입니다. 코드를 쓰기 전에 질문을 통해 구조를 먼저 정하고, CLAUDE.md와 DEVELOPMENT_ROADMAP.md를 만들어 이후 작업의 공통 기준으로 삼습니다. (GitHub)

결국 이 도구는 “AI에게 빨리 시키는 사람”보다, AI와 함께 오래 유지할 프로젝트를 시작하는 사람에게 더 유용합니다. 특히 첫 프로젝트부터 구조가 잡힌 상태로 출발하고 싶은 개발자, 세션이 바뀌어도 맥락이 유지되길 원하는 개발자, 여러 에이전트가 같은 원칙 아래 움직이게 만들고 싶은 팀에게 잘 맞는 접근입니다.

핵심 요약

• Claude Code 초반 실패는 종종 모델 성능보다 초기 구조 부재에서 시작된다.
• 공개 저장소 기준 핵심 스킬인 /project-init는 인터뷰를 통해 CLAUDE.md와 로드맵을 먼저 만든다. (GitHub)
• 핵심은 “코드 생성”보다 불변 조건과 규칙을 먼저 고정하는 것이다.
• 세션 전환, 에이전트 충돌, 늦은 하드 룰 추가 문제를 줄이는 데 특히 유리하다.
• 다만 현재 공개 문서상 명확히 확인되는 범위는 /project-init 중심이므로, 다른 구성 요소는 별도 문서 확인이 필요하다. (GitHub)