공개 기능 중심의 전체 조망

사용자 관점의 구성도

Claude Code는 고정된 내부 소스 트리보다, 사용자가 구성하고 검증할 수 있는 기능의 관계로 이해하는 편이 오래간다. 프로젝트 지시사항, 권한, 도구, 확장, 세션이 에이전트 루프에서 만난다.

프로젝트 지시사항·규칙
          │
          ▼
 Claude Code 세션과 에이전트 루프
   │          │            │
   ▼          ▼            ▼
권한 정책   내장 도구       확장
             │        ├─ skills: 재사용 절차
             │        ├─ hooks: 결정적 검증
             │        └─ MCP: 외부 도구·데이터
             ▼
       파일·셸·테스트 결과

세션은 이전 대화와 도구 결과를 이어 주지만, 파일 변경을 보관하는 버전 관리 시스템을 대체하지 않는다. 따라서 결과를 신뢰하려면 대화 요약뿐 아니라 diff, 테스트, 배포 관찰을 함께 확인해야 한다.

확장 기능의 역할 분담

| 요소 | 해결하는 문제 | 안전한 기본값 | | --- | --- | --- | | CLAUDE.md와 rules | 프로젝트 관례와 범위 전달 | 짧고 검토 가능한 지시 | | skills | 반복 작업의 방법과 절차 | 필요한 스킬만 로드 | | hooks | 항상 실행할 검사·감사 | 실패 시 차단 또는 명확한 보고 | | MCP | 외부 서비스의 도구·데이터 | 서버별 최소 권한과 신뢰 검토 | | subagents | 독립 하위 작업 분리 | 결과와 파일 범위를 명시 | | agent teams | 상호 조율이 필요한 실험적 협업 | 작은 가역 작업에서 검증 | | Agent SDK | 애플리케이션 내부의 에이전트 운영 | 격리·승인·관측을 앱이 책임 |

이 표에서 중요한 것은 기능을 많이 켜는 일이 아니다. 같은 보안 규칙을 skill 프롬프트에 숨기고 hook·권한 정책으로 다시 구현하면 검토가 어려워진다. 절차는 skill, 결정적 강제는 hook, 외부 연결은 MCP, 사용자 승인과 도구 범위는 권한 정책에 둔다.

운영 루프

작업 요청
  → Plan mode로 범위·위험 확인
  → 최소 권한으로 구현 또는 조사
  → 테스트·정적 검사·diff 검토
  → 결과·승인·실패 원인 기록
  → 필요한 지시사항과 자동화만 개선

외부 도구와 웹 콘텐츠에는 프롬프트 인젝션이 포함될 수 있다. 따라서 MCP 결과를 명령으로 그대로 실행하지 않고, 권한 범위·명령·변경 파일을 분리해 확인한다. 자동화 환경에서는 작업공간, 네트워크, 비밀, 비용·턴 한도를 모두 명시한다.

변화가 빠른 기능을 다루는 법

Agent teams와 Remote Control처럼 실험 또는 연구 미리보기로 표시된 기능은 문서의 현재 상태와 제한을 함께 읽는다. 공개 문서에 없는 기능명, 환경 변수, 패키지, 내부 메시지 형식은 교육 예제와 운영 설정에서 제외한다. 필요하다면 기능을 ‘지원 여부 미확인’으로 기록하고 공식 릴리스 노트나 레퍼런스가 확인된 뒤에만 사용한다.

이 원칙을 따르면 Claude Code의 UI나 내부 구현이 변해도 학습자는 같은 질문으로 설계를 검토할 수 있다. 어떤 권한이 필요한가, 누가 결과를 검증하는가, 실패하면 어떻게 되돌리는가, 그리고 이 사용법은 공식 계약으로 문서화되어 있는가. 이것이 안전하고 유지 가능한 코딩 에이전트 운영의 큰 그림이다.

---

퀴즈를 불러오는 중...