Please enable JavaScript.

Coggle requires JavaScript to display documents.

Claude Code, 이렇게 길어지는 경우 .claude/rules 하위에 파일을 분리하여 세부적인 내용을 정리하는 것이 좋다.…

- - - - 프로젝트 디렉토리 구조에 따라 참조해야 할 rule을 CLAUDE.md로 계층화해놓으면 클로드가 해당 디렉토리에 작업을 할 때 자동으로 해당 계층의 CLAUDE.md를 읽고 병합하여 내용을 적용한다
        
        각 디렉토리별 CLAUDE.md가 많아져서 계층적으로 적용시 총합 500라인이 넘어가면 컨텍스트가 날아갈 수 있음. 이는 컨텍스트 auto compaction으로 인해 지침이 유실될 수 있기 때문이다.
        
        해결방법
        
        skill로 분리하는 것도 한가지 방법
    - - xml을 활용하는 것은 Claude 프롬프트 엔지니어링 모범 사례에서 권장하는 형식이다.
  - - - 전체 대화 컨텍스트가 필요하지 않은 경우에만
        sub agent를 사용하는 것이 올바른 사용법임
    - - 실무 관점에서 아래 3가지로 작업 계획을 진행
        
        광범위한 코드베이스 검토 -> explorer
        
        문제 해결 솔루션 도출 및 트레이드 오프 계산 -> architect
        
        사이드이펙트 검토 -> guardian
      - 작업계획에서는 특히 광범위한 코드베이스를 읽고,
        복잡한 맥락 소화를 해야 하기 때문에
        단일 claude 세션으로 진행시 매우 비효율적일 수 있음.
        각 특화 작업을 sub agent에게 맡기고,
        핵심 내용만 받아서 메인 에이전트가 처리하면
        컨텍스트 비용도 아끼고, 작업 퀄리티도 높일 수 있게 됨
  - - - 1. 마크다운 파일 생성 및 저장
        
        반복적인 워크플로우(디버깅, 배포, 코드 리뷰 등)나 도메인 지식을 마크다운 파일로 작성합니다. 이 파일을 프로젝트 내의 .claude/commands/ 폴더에 저장하거나, 모든 프로젝트에서 전역으로 사용하려면 ~/.claude/commands/ (또는 ~/.claude/skills/) 폴더에 저장합니다. 저장된 파일의 이름(또는 패키징된 이름)이 곧 /review-pr이나 /deploy 같은 호출 가능한 슬래시 명령어가 됩니다.
      - 2. 파일 구조 작성 (YAML과 본문) Skill 파일은 크게 설정 영역과 지시문 영역으로 나누어 작성하는 것이 좋습니다.
        
        YAML Frontmatter (상단 설정): Skill의 이름, 설명, 작동 방식 등 메타데이터를 정의합니다. 💡 토큰 절약 팁: 여기에 disable-model-invocation: true를 설정하면, 사용자가 직접 슬래시(/) 명령어로 호출하기 전까지는 Claude의 컨텍스트에 로드되지 않도록 숨길 수 있습니다. 이를 통해 불필요한 토큰 소비를 0으로 줄일 수 있습니다. Markdown Body (프롬프트 본문): 실제 수행할 작업 절차, 검토 체크리스트, 참조할 API 가이드 등을 자연어로 구체적으로 작성합니다.
      - 생성한 Skill 사용하기 생성된 Skill은 두 가지 방식으로 작동합니다.
        
        수동 호출: 사용자가 직접 대화창에 /skill명을 입력하여 특정 워크플로우를 즉시 실행합니다. 자동 로드: 수동 호출 전용으로 설정하지 않은 경우, Claude는 세션 시작 시 Skill의 설명(Description)을 읽어두고 현재 작업과 연관성이 높다고 판단될 때 스스로 판단하여 전체 내용을 컨텍스트에 로드하여 사용합니다.
  - - - CLAUDE.md 파일과의 차이점
        
        작업 루트 디렉토리부터 상위 디렉토리까지의 CLAUDE.md를 추가 병합.
        이는 특정 확장자에만 규칙을 적용하는 등의 미세한 제어는 불가함.
        컨텍스트를 더 효율적으로 사용하고 미세제어하기 위해서는 rule에 추가하는 것이 더 나음
        
        CLAUDE.md의 계층적 적용은 단순한 룰이라 편하다.
        하지만 복잡한 프로젝트의 경우 어떤 규칙이
        어디에 선언되어있는지 파악하기 어렵다.
        rule의 경우 하나의 디렉토리에 모듈식으로 구성할 수 있어 유지보수에 매우 좋다.
        특히, frontend, backend 등 하위 디렉토리를 만들어 논리적으로 구조화를 하기에도 좋다
      - Skill과의 차이점
    - - 특정 파일이름 및 디렉토리 경로와 일치하는 경우 지침이 주입됨.
        따라서 언어별 혹은 디렉토리별 지침을 로드해야 할 때 사용
      - 상단 YAML 포매터에 paths 필드르 사용하여
        특정 파일 패턴을 지정할 수 있음.
        정확히 해당 패턴과 일치하는 파일을 열고 작업할 때만 규칙이 컨텍스트에 로드되기 때문에 컨텍스트를 획기적으로 절약
      - symbolic link를 지원.
        사내 표준 가이드라인이나 공통된 별도 공유 규칙세트를 만들어두고,
        .claude/rules 하위에 링크를 하여 쉽게 재사용이 가능.
        팀단위, 여러 조직단위에서 공통적인 지침하에 프로젝트를 진행할 때에도 적합한 방식
- - - - 특정 디렉토리나 확장자에게만 적용되는 규칙이라면
        .claude/rules 폴더 하위에 마크다운으로 정의한다.
        이 규칙들은 작업중인 파일 경로와 일치할 때만 컨텍스트에 로드되므로 토큰을 크게 절약할 수 있다
  - - - 광활한 코드검색은 서브에이전트에게 맡기는 것이 유리하다.
        서브 에이전트는 자체 컨텍스트 창에서 코드를 탐색하며, 작업이 끝나면 핵심만 전달하기 때문에 메인 컨텍스트가 빠르게 차오르는 것을 막고 토큰을 절약할 수 있다
    - - LSP(language Server Protocol)을 활용해 IDE에서 코드 정의를 찾아가는 방식으로 claude에게 코드 탐색을 시킬 수 있도록 한다.
        전체 풀스캔(grep)은 시간도 오래걸리고 너무 막대한 토큰을 사용하게 된다
- - - - 비용 제어를 위해 일단 팀의 규모를 작게 시작
      - 조정 작업에는 비용 효율이 좋은 sonnet 모델을 팀원으로 사용
      - 활성화된 팀원은 유휴 상태에서도 계속 토큰을 소비하기 때문에
        작업이 끝나면 팀을 정리해야 함
- - - - CLAUDE.md
        
        프로젝트 루트 디렉토리에 전역 지침서를 작성한다.
        팀과 해당 프로젝트의 컨벤션을 명시하는 것이라 생각하면 된다
        
        매 세션마다 로드되기 때문에 최대 200자를 넘기지 않도록 한다
        
        들어가는 내용 예
        
        코딩 스타일 가이드
        
        빌드 및 테스트 명령어
        
        브랜치 네이밍 규칙
        
        해당 프로젝트 개발에 참여하는 모든 팀원이 동일한 프로젝트 컨텍스트와 지침을 바탕으로 개발을 할 수 있도록 하기 위한 목적이다
        
        계층적인 파일 배치 활용
        
        CLAUDE.md를 상위 디렉토리부터 하위 디렉토리까지 병합해서 사용할 수 있음. 즉, 프로젝트 루트에 전역 설정, 특정 패키지나 폴더 하위에 필요한 CLAUDE.md를 추가로 둬서 그 도메인에만 해동하는 컨텍스트를 넣어서 계층화가 가능함
    - - 중앙 집중식 청구가 가능한 claude for teams or enterprise 사용이 적합
      - Amazon Bedrock이나 Google Vertex AI와 같은 클라우드 제공자를 활용하는 것도 방법
      - 비용 폭탄을 막기 위해 claude console에서 월간 지출 한도를 설정해야 한다. 예: 팀원 수 x $200
      - 조직 규모에 따라 사용자당 권장되는 TPM(분당 토큰 수)와 RPM을 설정
- - - - git worktree를 활용
        
        worktree를 활용하면 메인 프로젝트 디렉토리 하위에 기존 저장소의
        원격 내용을 공유하면서도 자체 파일 상태와 독립적인 브랜치를 가지는 격리된 작업 디렉토리가 생성된다.
        
        IDE에서 효과적으로 쓰려면 해당 worktree를 프로젝트 루트로 새롭게 프로젝트 환경을 여는 것이 좋다
        
        서로 다른 터미널 탭에서 각각 worktree를 열어두면,
        한 곳에서는 기능을 개발하고 다른 곳에서는 버그를 수정하더라도
        Claude 인스턴스끼리 서로 간섭하거나 코드가 엉키지 않고 안전하게 병렬 작업을 수행할 수 있다
        
        디렉토리가 분리된 것이기 때문에
        worktree에 enter한 다음, 거기에서 branch checkout을 하면 된다
        
        예시 시나리오
        
        jira 티켓 넘버 API-001, API-002, API-003은 서로다른 성격의 작업인데 career-api라는 동일한 프로젝트에서 진행돼야 함. 서로 성격은 다른데 같은 service 로직이나 controller 로직을 건드릴 수 있음. 지금 상황에서 동시에 3가지 태스크를 모두 진행하고 싶음
        
        터미널에서 Worktree 플래그를 줘서 각 터미널을 실행한다.
        claude -w API-001
        
        IDE에서 .claude/worktrees/API-001, 002, 003에 복사된 프로젝트를 open한다. 각 IDE의 격리된 worktree 작업공간과 터미널이 하나의 작업 pair라고 보면 된다
        
        같은 프로젝트지만 완전히 격리된 상태에서 작업이 가능하다.
        같은 service 로직이나 controller 로직을 건드려도 상관이 없다.
        
        각 worktree 작업을 해당 worktree branch에 commit한 뒤, pr을 올린다. 원격 branch에 작업물이 올라가면 worktree가 삭제돼도 작업은 보존된다.
        
        Finder에서 숨김처리된 디렉토리 찾을 때는 cmd + shift + .
        
        Worktree에서 작업할 때 git repo에 CLAUDE.md가 버전관리로 올라가있어야한다. 그래야 worktree 생성시 각 디렉토리 계층에 맞게 CLAUDE.md가 적용된다.
        만약 안돼있으면 기존의 rule들이 엄격하게 적용이 안된다.
    - - 예시 시나리오
        
        plan 모드로 작업계획을 완료한 상태야. 하나의 branch에서 작업할 계획인데, 한쪽은 app/jobs 디렉토리 하위에 새로운 백그라운드 job을 만들고 관련 테스트코드를 작성해야해. 한쪽은 app/controllers에서 새로운 API 진입점을 만들고 api 문서도 만들어야하고. 또 다른 쪽에서는 app/services에서 실제 복잡한 비즈니스 로직을 구현해야해
        
        현재 프로젝트 루트에서 3개의 독립된 터미널 창을 연다
        
        각 터미널에서 claude --fork-session을 사용.
        plan 모드에서 논의했던 계획(원본 대화 기록)을 그대로 물려받으면서 완전히 독립적인 세션 ID가 3개 생성됨.
        
        역할 분담 및 실행한다. 터미널1은 job 작업을, 2는 controller 작업을, 3는 services 작업을 실행한다
      - fork session을 활용
        
        claude code는 사용자가 작업하는 동안
        자동으로 실시간 저장을 수행함
        
        사용자 메시지, claude 응답, 도구 사용 내역 및
        실행결과가 발생할때마다 로컬에 세션 기록이 남음
        이를 바탕으로 언제나 resume하거나 fork를 할 수 있음
        
        claude가 코드를 수정하기 전에 항상 영향을 받는 파일들의
        스냅샷을 생성함. 이 체크포인트가 있어 롤백이 가능
        
        fork된 세션들끼리 동일한 디렉토리 파일을 건드리게 되면
        덮어쓰기 충돌이 발생할 수 있음.
        
        프롬프트를 통해 파일 접근 범위를 엄격하게 분리하기
        
        동일한 파일을 동시에 건드릴 가능성이 있다면
        아예 작업 자체를 worktree로 나누어서 별도의 branch 작업으로 분리하는 것이 효과적
      - Agent Teams를 활용