Claude Code의 핵심만 담은 경량화 버전 'nano-claude-code' 개발기

실용적 조언

에이전트 개발 시 git diff를 활용해 모델에게 코드 변경 결과를 시각화하여 전달하면 정확도를 높일 수 있다.
복잡한 UI 대신 CLI와 단순한 파일 기반 설정(NANO.md)을 사용해 코드베이스의 인지 부하를 줄일 수 있다.

섹션별 상세

에이전트의 핵심 루프는 기술(skills)과 규칙 로드, 사용자 메시지 추가, Anthropic API 호출, 도구 실행의 반복으로 구성된다. 모델이 중단 신호를 보낼 때까지 이 과정을 자동화하여 복잡한 코딩 작업을 수행한다. 15개의 파일로 구성된 간결한 아키텍처를 통해 전체 시스템의 작동 원리를 한눈에 파악할 수 있도록 설계했다.

파일 변경 도구가 git diff --no-index를 통해 차이점을 반환하도록 설계했다. 모델은 단순히 '쓰기 성공'이라는 메시지 대신 구체적인 코드 변경 내역을 구조화된 데이터로 수신한다. 이를 통해 모델이 자신의 수정 사항을 정확히 인지하고 다음 단계의 추론을 수행하는 데 필요한 피드백 루프를 강화했다.

상용 제품의 복잡한 UI 레이어와 관리 기능을 과감히 제거하고 핵심 로직만 남겼다. React/Ink 기반의 UI, 동시 도구 오케스트레이션, 과금 및 분석 시스템 등을 제외하여 코드베이스의 인지 부하를 최소화했다. 개인 개발자가 에이전트의 내부 구조를 완전히 이해하고 커스텀할 수 있는 유지보수성을 확보했다.

MCP(Model Context Protocol)를 일급 시민으로 취급하여 에이전트의 기능을 확장 가능하게 만들었다. NANO.md라는 로컬 지침 파일과 JSONL 형식의 트랜스크립트 기록을 통해 작업의 투명성을 높였다. 위험한 작업에 대한 승인 게이트를 유지하여 자율 실행 중 발생할 수 있는 오류를 방지했다.

용어 해설

모델 컨텍스트 프로토콜(MCP): — Anthropic이 제안한 개방형 표준으로, AI 모델이 로컬 데이터나 외부 도구에 안전하고 표준화된 방식으로 접근할 수 있게 해주는 프로토콜이다. 에이전트의 기능을 모듈식으로 확장할 수 있게 하며, 다양한 데이터 소스와의 연동을 단순화하여 에이전트의 범용성을 높이는 핵심 기술이다.
JSON 라인(JSONL): — 각 행이 하나의 독립된 JSON 객체로 구성된 텍스트 파일 형식이다. 대규모 로그 데이터나 에이전트의 실행 트랜스크립트를 저장할 때 유리하며, 파일 전체를 메모리에 올리지 않고도 순차적으로 읽거나 추가할 수 있어 데이터 처리 효율성이 높다.
깃 디프(Git Diff): — 두 파일이나 커밋 간의 차이점을 추출하는 도구이다. 이 프로젝트에서는 --no-index 옵션을 사용하여 Git 저장소 외부의 파일 변경 사항을 비교하며, 모델에게 코드 수정 결과를 텍스트 기반의 구조화된 형식으로 전달하여 변경 내용을 명확히 인지하게 돕는다.
코딩 에이전트(Coding Agent): — 소프트웨어 개발 작업을 자율적으로 수행하는 AI 시스템이다. 코드 작성, 디버깅, 리팩터링 등의 작업을 위해 파일 시스템 접근 및 도구 실행 권한을 가지며, 사용자의 요구사항을 분석하여 일련의 코딩 과정을 스스로 계획하고 실행하는 역할을 한다.

언급된 도구

Claude Code추천

원본 코딩 에이전트

MCP추천

에이전트 기능 확장 프로토콜

nano-claude-code추천

경량화된 오픈소스 코딩 에이전트

언급된 리소스

GitHubnano-claude-code GitHub Repository