Claude Code로 코드를 짜다 보면 은근히 답답할 때가 있다.
웬만한 건 잘 짜는데 코드베이스가 길어지거나,
특정 라이브러리를 사용할 때 버전 문제로 토큰이 물처럼 쏟아지는 등의 경우가 있다.
나는 ROS2를 활용해 관련 프로젝트를 진행하려는데,
경험상 ROS는 버전별 편차가 심한데다,
QoS를 요구사항에 맞추지 못하고 아무렇게나 쓴다거나..
AI도 이런 데서 헛발질할 것 같았다.
그래서 AI 에이전트용 ROS2 관련 스킬을 하나 만들어보기로 했다.
👉 dbwls99706/ros2-engineering-skills
근데 제목처럼 SKILL.md를 라우터로 활용하는 게 좋다는 글을 봤었다.
왜 SKILL.md에 정보를 몰아넣어서 한 파일만 거치게 하지 않고 라우터처럼 쓰는 게 효율이 좋을까?
한 파일에 다 넣으면 망한다
Agent Skills 표준은 단순하다.
SKILL.md 파일 하나에 도메인 지식을 적어두면 에이전트가 필요할 때 로드해서 참고한다.
근데 ROS2는 범위가 너무 넓어서,
workspace 세팅, QoS, tf2, ros2_control, Nav2, MoveIt, 실시간, micro-ROS, 멀티로봇…
이걸 한 파일에 우겨넣으면 colcon build 질문 하나 하는데도 Nav2 지식까지 같이 컨텍스트에 올라온다.
그렇게 되면 토큰도 태우고,
상관없는 내용이 섞이면 답도 엉뚱해진다.
라우터와 지식을 분리하여 최적화
라우터는 원래 네트워크 용어다.
들어온 신호를 보고 "이건 어디로 보내야지" 하고 길만 정해주는 녀석이다.
집에 있는 공유기가 대표적이다.
유튜브 요청은 인터넷 쪽으로, 프린터 요청은 내부망으로 분기시켜주는 딱 그 역할이다.
같은 개념을 SKILL.md에 적용해보자는 것이다.
구조는 클로드 공식의 설명과 같이 이렇게 잡았다.
SKILL.md는 라우터다. 500줄 이내로 너무 길어지지 않게 판단 로직만 담는다.- 실제 지식은
references/폴더에 도메인별로 쪼갰다.
유저 질문이 들어오면 에이전트는 먼저 SKILL.md를 본다.
거기서 "QoS 증상이면 communication.md로, callback이 안 불리면 nodes-executors.md로" 같은 진단을 하고,
필요한 파일만 그때 로드한다.
references엔 ROS가 조용히 틀리게 만드는 함정들도 모여있다.
예를 들어 camera_link 프레임으로 이미지를 퍼블리시하면 에러는 안 나는데 AprilTag나 비주얼 SLAM 결과가 전부 90도 돌아간 채로 나온다. (옵티컬 프레임과 바디 프레임의 축 정의가 달라서 그렇다.)
에이전트가 코드 짜기 전에 이런 규칙부터 참고하도록 라우터가 길을 잡아준다.
근데 또 너무 얕으면 안 됨
처음엔 "라우터니까 상황에 맞는 파일 이름만 적어두면 되겠지" 싶었는데,
그러면 에이전트가 애매한 질문에서 길을 잃는다.
예를 들어 "노드가 가끔 메시지를 놓친다"는 증상은 QoS 문제일 수도,
callback group 문제일 수도,
실시간 튜닝 문제일 수도 있다. 그래서 SKILL.md에는 "어떤 증상일 땐 어디로" 같은 진단표를 같이 넣었다.
목차가 아니라 의사결정 트리에 가깝다고 보면 된다.
마무리
라우터 패턴의 이점은 명확하다. 필요한 도메인만 컨텍스트에 올라가고,
수정할 때 영향 범위도 좁고,
사람이 읽어도 전체 구조가 한눈에 파악된다.
굳이 공식문서를 뒤지거나 하는 식으로 토큰을 낭비하는 행동 자체를 문서로 제약해둘 수 있다.
Apache-2.0이라 그냥 가져다 써도 되고,
references 패턴만 본인 프로젝트 CLAUDE.md에 옮겨 써도 된다.
ROS2 관련하여 작업할 때 Claude Code 등의 에이전트를 입혀서 쓰는 분들이 있다면 피드백 주면 감사
