Claude Code로 구축한 로보틱스 운영 인프라
이전 글에서 로보틱스 스타트업의 생존 전략을 정리했다. 이 글에서는 그 전략을 실행하기 위해 실제로 구축한 Claude Code 인프라를 다룬다.
만든 건 robotics-ops라는 워크스페이스다. 4가지 시스템이 하나로 연결되어 있다.
전체 흐름
고객 수주
→ /new-si-project로 프로젝트 생성
→ /decision으로 설계 결정 기록
→ 개발 (Claude Code + 제어기 SDK)
→ /daily-log로 매일 기록
→ /build-sdk-docs로 고객용 문서 생성
→ /protect-md로 IP 보호 패키징
→ 납품핵심은 **“사람이 초반에 좀 고생하면, 이후는 Claude Code가 맥락을 읽고 병렬로 돌릴 수 있다”**는 것이다.
1. SDK용 CLAUDE.md 자동 생성
문제
제어기를 고객에게 납품할 때, SDK만 던져주면 고객은 사용법을 모른다. 그렇다고 매번 문서를 처음부터 쓰기엔 고객마다 로봇 구성이 다르다. A고객은 LiDAR만, B고객은 카메라+힘센서를 쓴다.
해결
모듈식 CLAUDE.md 조합 시스템을 만들었다.
8개의 독립된 인스트럭션 모듈이 있다:
| 모듈 | 내용 |
|---|---|
| safety | 안전 규칙 (E-STOP, 리밋 스위치, 워치독) |
| core-system | 시스템 아키텍처, Python 패키지 구조 |
| motor-control | CiA 402 상태머신, 단축/다축 제어 API |
| sensor-integration | LiDAR, 카메라, IMU, 힘센서 연동 |
| ros2-nodes | 기본 노드, 런치 파일, 커스텀 노드 패턴 |
| communication | CANopen, EtherCAT, Serial 프로토콜 |
| examples | 픽앤플레이스, 센서 모니터링 등 실전 예제 |
| troubleshooting | 진단 명령어, 자주 발생하는 문제 해결 |
고객별 config.yaml에 어떤 모터, 어떤 센서, 어떤 프로토콜을 쓰는지 적으면:
customer: "ABC Manufacturing"
controller_type: "CANopen CiA 402 (Maxon EPOS4)"
sensor_list: "Hokuyo LiDAR, Intel RealSense D435"
max_velocity: "3000 rpm"
modules:
- safety
- motor-control
- sensor-integration
- troubleshootingbuild_claude_md.py를 돌리면 573줄짜리 완전한 CLAUDE.md가 자동 생성된다. 이 파일이 SDK와 함께 납품되면, 고객이 Claude Code를 열었을 때 바로 로봇 시스템을 이해하고 코드를 짤 수 있다.
템플릿도 3종류다:
- minimal - 단순 배포용, 안전규칙+기본 구조+모터+트러블슈팅만
- standard - 일반 고객, 전체 모듈 포함
- advanced - 숙련 개발자용, PID 튜닝/안전영역 설정 등 고급 기능 포함
2. SI 워크플로우 자동화
문제
SI 프로젝트를 5개씩 병렬로 돌리려면, 매번 폴더 만들고 설정 파일 만들고 git init 하는 시간이 아깝다. 현장에 가서 “지금 이 프로젝트 어디까지 했더라?” 파악하는 시간도 아깝다.
해결
Claude Code 커맨드 7개를 만들었다.
/new-si-project - 프로젝트 스캐폴딩
/new-si-project Samsung-welding-line3 "삼성중공업" offline이 한 줄이면 다음이 자동 생성된다:
- CLAUDE.md (프로젝트별 인스트럭션)
- config/ (로봇 설정, 네트워크 설정)
- docs/ (현장 조사서, 요구사항, 인수인계 문서 템플릿)
- decisions/ (의사결정 기록 디렉토리 + 초기 ADR)
- src/, tests/ (코드 디렉토리)
- git 초기화 + 초기 커밋
/status - 프로젝트 현황 대시보드
==================================================
프로젝트 현황 / Project Status
날짜: 2026-02-18 네트워크: online
==================================================
Git: main - clean
Last commit: a1b2c3d Initial scaffold (2 hours ago)
최근 결정사항:
- ADR-0003: 모터 드라이버 선택
- ADR-0002: 센서 배치 결정
- ADR-0001: 프로젝트 시작
주의사항:
- src/control.py:42 - TODO: PID 튜닝 필요
==================================================프로젝트에 들어가서 /status 한번이면 현재 상태가 바로 파악된다. 프로젝트 5개를 전환하면서 쓸 때 이게 핵심이다.
/troubleshoot - 로봇 진단 가이드
안전 확인부터 시작해서, 문제 분류 → 진단 → 이력 검색 → 해결까지 가이드해준다. 현장에서 비상 상황일 때 당황하지 않도록.
그 외에도:
- 4종 체크리스트 (출장 전, 현장 설정, 오프라인, 인수 테스트)
- 오프라인 번들러 (인터넷 없는 현장에서도 pip 패키지 설치 가능)
- SI 에이전트 페르소나 (Claude Code가 현장 엔지니어 역할을 할 때의 행동 규칙)
3. 의사결정 기록 시스템
문제
AI 시대에는 코드보다 **“왜 이런 결정을 내렸는가”**가 더 중요하다.
내가 AI로 코드를 짰다. 다음에 오는 사람도 AI로 짤 것이다. 코드는 AI가 읽으면 된다. 하지만 “왜 CAN 대신 EtherCAT을 골랐는지”, **“왜 이 센서 배치를 선택했는지”**는 코드에 안 나와있다.
해결
ADR(Architecture Decision Record) 기반 시스템을 만들었다.
/decision "모터 드라이버 선택" 하면 ADR 파일이 자동 생성된다:
# ADR-0002: 모터 드라이버 선택
## 배경
6축 아암의 관절 모터를 선택해야 한다. 정밀도와 가격의 트레이드오프.
## 검토한 옵션
### Option A: Maxon EPOS4
- 장점: 높은 정밀도, CiA 402 완벽 지원
- 단점: 가격이 2배
### Option B: 오리엔탈모터 AZ 시리즈
- 장점: 가격 저렴, 국내 AS 빠름
- 단점: 정밀도 약간 낮음
## 결정
Option B 선택. 이유: 이 프로젝트는 정밀도 ±0.1mm 수준이면 충분하고,
AS 응답 속도가 현장에서 더 중요하다.
## 결과
- 모터 단가 40% 절감
- 대신 소프트웨어에서 뉴럴넷 보정을 적용해야 할 수 있음핵심은 **“왜(Why)“**에 집중하는 것이다. 이 기록이 있으면, 6개월 뒤에 다른 엔지니어가 와서 Claude Code에게 “이 프로젝트 결정 이력 파악해줘”라고 하면 바로 맥락을 잡을 수 있다.
**/daily-log**로 매일의 소소한 결정도 기록한다:
| 시간 | 결정 | 이유 | 영향 |
|---|---|---|---|
| 10:30 | PID Kp를 1000→600으로 낮춤 | 3축에서 진동 발생 | 안정성 향상, 응답 약간 느려짐 |
| 14:00 | 센서 주기를 10ms→20ms로 변경 | CPU 과부하 | 부하 50% 감소 |
검색 스크립트도 있어서, 키워드/태그/날짜로 과거 결정을 찾을 수 있고, 인수인계 시 모든 결정을 하나의 문서로 내보낼 수 있다.
4. MD 파일 보호
문제
CLAUDE.md에 담긴 인스트럭션은 우리의 지적재산이다. 고객에게 주긴 해야 하는데, 고객이 내용을 그대로 읽고 복제할 수 있으면 안 된다.
해결
고객 환경에 따라 3가지 전략을 만들었다.
온라인 고객: API 서버 방식
고객에게는 빈 껍데기 CLAUDE.md만 준다. 실제 인스트럭션은 우리 서버에서 API 키로 인증 후 제공한다. 고객 디스크에 저장되지 않는다.
고객 CLAUDE.md → "이 서버에서 인스트럭션을 가져와" → API 인증 → 전체 내용 로드오프라인 고객 (일반): 난독화 방식
인스트럭션을 base64 + XOR로 인코딩하고, 5개 랜덤 파일명 청크로 분할한다. 사람이 파일을 열어봐도 읽을 수 없다. Claude Code에서 디코더를 실행해야만 원본이 복원된다.
실제 테스트: 인코딩 → 디코딩 → 원본과 100% 일치 검증 완료.
오프라인 고객 (고보안): 패스프레이즈 방식
강한 패스프레이즈로 암호화하고, 패스프레이즈는 전화나 대면으로 별도 전달한다.
4개 시스템이 연결되는 방식
이 시스템들은 독립적이 아니라 서로 연결되어 있다:
- Task 1 → Task 4: SDK CLAUDE.md를 생성하면 → 보호 패키징으로 넘어감
- Task 2 → Task 1: SI 프로젝트 생성 시 → 해당 고객 맞춤 CLAUDE.md 포함
- Task 2 → Task 3: 모든 SI 프로젝트에 → decisions/ 디렉토리 자동 생성, /status가 최근 결정 표시
- Task 3 → Task 1: SI에서 발견된 트러블슈팅 → SDK 문서 개선에 반영
실제 사용 시나리오
시나리오: 새로운 SI 프로젝트 착수
# 1. 프로젝트 생성 (30초)
/new-si-project Hyundai-welding-cell "현대중공업" offline
# 2. 로봇 설정 편집
# config/robot-config.yaml에 모터, 센서 정보 입력
# 3. 고객 맞춤 SDK 문서 생성
/build-sdk-docs config.yaml
# 4. 개발하면서 결정 기록
/decision "용접 시퀀스 제어 방식 선택"
# 5. 매일 퇴근 전
/daily-log
# 6. 납품 전 보호 패키징
/protect-md obfuscated ./output/CLAUDE.md
# 7. 상태 확인
/status이 흐름이 자리 잡으면, 엔지니어 한 명이 프로젝트 5개를 동시에 돌리면서도 모든 맥락이 추적된다. 다음 사람이 와도, 다음 AI가 와도, 이어받을 수 있다.
기술적 세부사항
만든 것들의 목록:
robotics-ops/
├── CLAUDE.md # 워크스페이스 루트 인스트럭션
├── .claude/
│ ├── commands/ (7개) # /status, /decision, /daily-log 등
│ ├── skills/ (3개) # si-workflow, decision-record, md-protection
│ └── agents/si-engineer.md # SI 현장 에이전트 페르소나
├── sdk-docs/
│ ├── modules/ (8개) # 조합 가능한 인스트럭션 블록
│ ├── templates/ (3종) # minimal, standard, advanced
│ └── generator/ # build_claude_md.py + config.yaml
├── si-workflow/
│ ├── templates/ # 프로젝트 스캐폴드 + 체크리스트 4종
│ └── scripts/ # scaffold.py, status_check.py, offline_bundle.py
├── decision-system/
│ ├── templates/ (4종) # ADR, 일일기록, 프로젝트 시작
│ └── scripts/ # 생성, 검색, 타임라인, 내보내기
└── md-protection/
└── strategies/ # online(API), offline(난독화/암호화)전체 코드는 Python으로 작성했고, ROS2 + CiA 402 기반의 로보틱스 스택에 맞춰져 있다. 모든 출력은 한국어+영어 이중언어를 기본으로 한다 (외국인 직원 현장 투입 대비).
마무리
이 인프라의 핵심 철학은 하나다:
“어떻게 하면 AI가 좀 더 적은 컨텍스트로 현재 상황을 파악할 수 있을까”
그 답이 잘 짜여진 CLAUDE.md이고, 체계적인 의사결정 기록이고, 자동화된 워크플로우다. 이것만 잘 갖춰두면, 사람이든 AI든 바로 이어받아서 작업할 수 있다.