Claude Code, 터미널 위 에이전트를 팀 워크플로에 얹기

3.1 핵심 구성요소 — Rules · Skills · Commands · Agents · Memory

Claude Code를 실무에 얹으려면 다섯 구성요소가 어떻게 맞물리는지부터 잡아야 합니다. Rules(규칙)는 CLAUDE.md에 적어 두는 상시 지침으로, 코드 스타일·금지 사항·빌드 절차처럼 매 요청에 늘 적용돼야 할 맥락을 담습니다. Skills(스킬, 필요할 때만 불러오는 능력 묶음)는 특정 작업의 절차와 참고 자료를 한 벌로 포장해 두었다가 관련 작업이 들어올 때 모델이 스스로 로드합니다. Commands(명령)는 /로 시작하는 단축 실행이고, Agents(서브에이전트, 독립된 맥락·모델·권한을 갖는 하위 작업자)는 큰 작업을 갈래로 나눠 맡깁니다. Agent Memory(기억)는 세션이 바뀌어도 남는 장기 기록으로, 반복 지시를 매번 다시 설명하지 않게 해 줍니다.

3.2 세션 운영 — 슬래시 명령 · 헤드리스 · 스트리밍 · 자동 모드

대화 세션은 맥락을 쌓아 가며 이어집니다. 맥락이 길어지면 /clear로 초기화하거나 /compact로 요약해 컨텍스트 윈도우(context window, 모델이 한 번에 참고하는 정보의 범위)를 관리합니다. 슬래시 명령은 /init·/review처럼 내장된 것과, .claude/commands/ 아래 마크다운으로 직접 정의하는 사용자 명령으로 나뉘며, 사용자 명령은 $ARGUMENTS로 인자를 받아 반복 작업을 표준화합니다. 헤드리스 모드(headless mode, 대화창 없이 한 번에 실행)는 claude -p 형태로 파이프라인에 붙여 결과를 JSON으로 받고, 스트리밍 모드는 입력·출력을 조각 단위로 주고받아 프로그램에 통합합니다. 자동 모드는 편집 승인을 매번 누르지 않고 에이전트가 이어서 실행하도록 풀어 주는 대신, 되돌리기 어려운 작업에는 승인 경계를 남겨 둡니다.

3.3 CLAUDE.md 계층 · 저장소 초기화 · settings.json

CLAUDE.md는 한 파일이 아니라 계층으로 겹쳐집니다. 사용자 홈(~/.claude/CLAUDE.md)의 개인 지침, 저장소 루트의 프로젝트 지침, 하위 디렉터리의 국소 지침이 위에서 아래로 합쳐지며, 범위가 좁을수록 그 폴더 작업에 더 구체적으로 걸립니다. 새 저장소에 붙일 때는 /init 명령이 코드베이스를 훑어 초안 CLAUDE.md를 만들어 주니, 여기서 팀 규약을 다듬으면 됩니다. settings.json은 동작 설정을 담는데, 저장소에 체크인하는 .claude/settings.json은 팀 공용 규칙(도구 권한 허용·차단·확인, 훅, 환경 변수)을 쥐고, settings.local.json은 각자 로컬 설정으로 커밋에서 제외합니다. 권한(permission)을 설정으로 명시해 두면 자동 모드에서도 위험한 명령을 걸러 낼 수 있습니다.

! 흔한 함정

• Skills와 서브에이전트를 같은 것으로 오해합니다 — Skills는 절차·자료를 포장한 능력 묶음이고, 서브에이전트는 독립된 맥락과 권한을 가진 하위 작업자로 역할이 다릅니다.
• CLAUDE.md를 한 파일로만 생각합니다 — 실제로는 홈·프로젝트 루트·하위 폴더가 계층으로 합쳐지며, 범위가 좁은 파일이 그 폴더 작업에 더 구체적으로 적용됩니다.
• settings.json과 settings.local.json을 뒤섞습니다 — 팀 공용 규칙은 체크인하는 settings.json에, 개인 설정은 커밋에서 제외하는 로컬 파일에 분리해야 합니다.
• 자동 모드를 무조건 편한 기능으로만 봅니다 — 배포·삭제처럼 되돌리기 어려운 작업에는 승인 경계를 남겨 둬야 안전합니다.