AI와 로봇 연구하기← repos

AI와 로봇 연구하기

Guide
00Ch.0 — 작업 구조를 남긴다
비싼 구독 모델을 쓰면 해결되지 않나?/SOTA 모델을 자체 서버에서 돌리면 어떤가?/그러면 우리가 해야 할 일은 무엇인가?
01Ch.1 — AI 답변은 후보로 둔다
잘하는 일/자주 틀리는 일/왜 이런 일이 생기는가/확인할 다섯 줄
02Ch.2 — 현재 상태부터 복원한다
증거의 무게/복원할 항목/복원 순서
03Ch.3 — 한 번에 하나만 바꾼다
작업 전에 적을 것/자주 나오는 작업 유형/실행 권한을 먼저 정한다/완료 보고는 좁게 쓴다
04Ch.4 — 논문과 코드를 맞춰 본다
남길 항목/확인할 질문/구현 상태 라벨
05Ch.5 — 숫자에는 조건이 붙는다
최소 기록/로보틱스 task에서 볼 항목/평가 조건에서 볼 항목
06Ch.6 — 실패 지점 찾기
기본 순서/ROS2 callback이 비어 있을 때/일반적인 로보틱스 task에서 성능이 갑자기 떨어졌을 때/기록 형식/구분해야 할 실패
07Ch.7 — 주장과 근거를 먼저 본다
답변 전에 볼 것/처리 순서/자주 생기는 실패
08Ch.8 — 남의 repo에서 습관만 가져온다
참고할 repo 유형/그대로 가져오면 빠지는 항목/옮길 때 볼 것
09Ch.9 — 로봇은 코드 밖에서 실패한다
로봇 실험에서 먼저 확인할 것/ROS에서 자주 막히는 지점/Docker에서 자주 빠지는 설정/하드웨어와 드라이버 신호/반복해서 막히는 패턴/에이전트에게 줄 정보/연구 루틴에 붙이는 법
Appendix
부록부록 A — 헷갈리기 쉬운 말들
기본 용어/근거의 무게/도구별로 볼 것/Claude 규칙을 Codex에서 쓸 때
부록부록 B — 빠른 시작 파일
도구 역할을 먼저 나눈다/Workspace를 나눈다/AGENTS.md 작성/첫 상태 체크리스트를 채운다/첫 AI 요청을 좁힌다/연구 루프를 하나만 고른다/결과를 기록에 남긴다
부록부록 C — 예시 workspace
파일 구조/이 예시가 보여주는 것/예시에서 배울 경계
부록부록 D — 작업 흐름을 남기는 법
다시 시작할 때 필요한 것/하나의 작업을 결과물로 남긴다/반복 실패를 다음 작업 전에 잡는다/매주 남길 세 줄/멈출 때
부록부록 E — 출처
External Agent And Skills Repos/Human-AI Action Theory Sources/LLM Agent And Grounding Sources/Model Serving And Product-Layer Sources/Evaluation And Reproducibility Sources/Argument And Manuscript Sources

Ch.0 — 작업 구조를 남긴다

AI는 연구 작업에서 유용하다. 큰 repo에서 관련 파일을 검색하고, 긴 로그에서 확인할 원인을 빠르게 찾아내고, 논문을 보고 코드를 프로토타입으로 구현하는 등 일반화 작업을 매우 빠르게 수행한다. 그러나 잘 못하는 부분도 분명 있다. 이 글을 읽는 사용자는 AI 모델을 다그쳐도 보고, 꾸짖어도 보고, 달래도 보고 하면서 사람과 똑같이 대해가며 더 나은 결과를 이끌어낸 경험이 있다. 그런데 늘 이렇게 할 수는 없지 않은가. 우리가 AI를 어르고 달래기 위해서 일을 하는 게 아니지 않은가. 이 아티클은 이 상황을 타개하는 원리와 도구를 소개하기 위해 작성하였다.

비싼 구독 모델을 쓰면 해결되지 않나?

일단 우리 연구실에서는 200 USD짜리 구독을 6개월째 해오고 있다. 좋은 모델을 쓰면 성능이 더 좋아지는 부분이 있기 때문이다. 그래도 작업 품질은 일정하지 않다. 문제는 상용 구독이 폐쇄형 서비스라는 점이다. 사용자는 통제할 수 없는 모델에 프롬프트만 입력한다. 공급자는 실제 parameter 수, token limit, backend routing, system prompt, cache, thinking 처리의 변화 정보를 제한적으로만 공개한다. Anthropic의 2026년 4월 Claude Code postmortem은 reasoning effort 변경, thinking cache bug, 짧은 답변을 유도한 system prompt가 품질 저하 보고로 이어졌다고 적었다. 공급자가 이런 항목을 바꿔도 우리는 알아채기조차 힘들다. 장기 연구에는 안정적인 작업 조건이 필요하다.

SOTA 모델을 자체 서버에서 돌리면 어떤가?

좋은 모델을 자체 서버에 올리면 공급자의 routing이나 quota 변화에서는 조금 자유로워진다. 그러나 상용 서비스가 제공하는 것은 LLM 가중치 하나가 아니다. 모델 선택, routing, system prompt, context 압축, cache, tool 호출, retrieval, 권한, 실행 환경을 묶은 작업 하네스다. 연구실에서 같은 효과를 내려면 논문 PDF, code path, 실험 로그, dataset convention, reviewer comment를 검색 가능한 단위로 정리하고, 질문마다 어떤 근거를 쓸지 정해야 한다.

이 문제를 부분적으로 해결하기 위해 retrieval을 모델 구조 안에 넣는 연구들이 이어졌다. REALM은 지식을 parameter에 모두 밀어 넣는 대신 pre-training 단계부터 retriever를 붙였다. DPR은 질문과 passage를 같은 dense representation 공간에서 맞추도록 dual encoder를 학습했다. RAG는 seq2seq model의 parametric memory와 Wikipedia dense index를 결합해 factuality, provenance, knowledge update 문제를 줄이려 했다. FiD, RETRO, Atlas도 retrieved passage를 generator가 읽는 방식, 큰 text database에서 chunk를 가져오는 방식, few-shot setting에서 retrieval을 쓰는 방식을 각각 밀고 갔다.

그러나 연구실에서 필요한 것은 이 논문들의 web-scale index가 아니다. 어느 논문 PDF, 어느 code path, 어느 실험 로그, 어느 dataset convention, 어느 reviewer comment를 어떤 단위로 잘라 둘지 정하는 일이다. 질문이 들어왔을 때 무엇을 찾아 붙일지도 정해야 한다. 답의 품질은 모델의 parameter뿐 아니라 바깥 자료를 얼마나 정확히 찾아 쓰느냐에 달려 있다.

Anthropic의 2026년 Claude Code 사용 분석은 이 분업을 실제 세션에서 관찰했다. 사용자는 목표, 접근 방식, 완료 기준을 정하는 쪽에 더 많이 개입했고, Claude는 파일을 고치고 명령을 실행하는 쪽을 더 많이 맡았다. 사용자의 전문성은 특히 문제를 구체적으로 세팅하고, 검증할 대상을 정확히 짚고, agent의 잘못된 판단을 바로잡는 능력으로 나타났다. 그러나 이 일을 매번 사람이 즉석에서 해낼 수는 없다. 이 글의 목적은 agent에게 읽힐 수 있는 작업 지침을 제공하는 것이다. agent가 이 내용을 바탕으로 repo의 AGENTS.md, project memory, 실험 기록, 주장·근거 표를 만들 수 있어야 한다.

그러면 우리가 해야 할 일은 무엇인가?

AI를 사람처럼 대하면 처음에는 잘 되는 것처럼 보인다. 더 자세히 설명하고, 다시 부탁하고, 틀렸다고 지적하면 답이 좋아질 때가 있다. 이 방식은 작업 방식으로 불안정하다. 매번 사용자가 상황을 기억하고, 모델의 답을 의심하고, 빠진 맥락을 다시 채워 넣어야 하기 때문이다.

연구 작업에서는 이 방식이 금방 한계에 닿는다. 실험은 며칠씩 이어지고, 원고는 여러 번 바뀌고, reviewer comment는 과거 결과와 현재 코드 상태를 동시에 요구한다. 이때는 AI가 틀리지 않게 만드는 작업 구조가 필요하다.

그래서 작업 환경부터 바꿔야 한다. 어떤 파일을 봤는지, 어떤 command를 실행했는지, 어떤 결과를 근거로 삼았는지를 남겨야 한다. 그래야 AI가 바뀌어도 같은 일을 다시 이어갈 수 있다. 이렇게 하면 모델 성능이 낮아져도 작업을 계속 붙잡을 수 있다. 좋은 모델은 더 빨리 찾고 더 잘 정리하겠지만, 성능이 낮은 모델도 같은 파일과 같은 로그를 보고 같은 절차를 따라갈 수 있다. 이 아티클은 그 절차를 만드는 도구들을 소개한다.

이 글은 사람이 처음부터 모든 규칙을 손으로 옮겨 적으라고 쓴 문서가 아니다. 새 연구 workspace를 만들 때는 agent에게 이 글을 읽히고, 자기 repo의 AGENTS.md, project memory, 실험 기록, 주장·근거 표를 만들게 해야 한다. 사람은 목표와 공개/비공개 경계, 검증 기준을 정한다. agent는 그 기준을 파일과 절차로 옮긴다. 이 글의 쓰임은 거기에 있다.

Ch.1 — AI 답변은 후보로 둔다

AI는 먼저 확인 대상을 만든다. 에러 원인, 읽을 파일, 실험 조건, 원고 문장처럼 실제 작업 전에 좁혀 볼 목록을 빠르게 만든다. 그 설명이 맞는지는 repo, 실행 결과, dataset, metric, 원고 주장을 보고 판단한다.

우리 연구실에서 로보틱스 연구 대화의 사용자 입력 27,759개를 직접 분류했다. 장점과 실패가 함께 보였다. AI는 큰 repo를 훑고, 긴 log를 나누고, 논문 문장과 code path를 맞춰 보는 데 도움을 줬다. 반복 실패도 뚜렷했다. 가장 자주 나온 것은 현재 실행 상태를 보지 않은 단정과 파일 존재를 실제 사용으로 보는 착각이었다. 조건이 다른 숫자의 비교와 실패 단계 혼합이 그다음이었다. 위험 비용을 무시한 원고 주장 확대는 빈도는 낮았지만, 한 번 생기면 비용이 컸다.

잘하는 일

AI는 눈앞의 텍스트와 파일을 빠르게 훑는다. 연구자가 좁혀야 할 범위를 줄여 준다.

잘하는 일 연구에서의 쓰임
확인 대상 생성 에러 로그에서 확인할 원인을 여러 개 뽑는다
탐색 보조 파일, 함수, config, figure, table 위치를 찾는다
구조 정리 긴 log나 reviewer comment를 단계별로 나눈다
초안 작성 rebuttal, README, command 설명의 첫 문장을 만든다
비교 정리 여러 repo, paper, 실험 조건의 차이를 표로 놓는다

확인 대상을 만드는 단계는 비용이 낮다. 틀린 설명이 섞여도 바로 실행하기 전까지는 연구 상태가 그대로다.

자주 틀리는 일

AI 답변은 확인할 후보를 준다. 현재 process가 살아 있는지, config가 runtime에서 읽혔는지, metric script가 같은 조건을 썼는지, reviewer가 공격한 주장에 답할 만큼 근거가 있는지는 파일과 실행 결과를 봐야 한다.

자주 틀리는 일 왜 문제가 되는가
보지 않은 현재 상태 확정 파일명, memory, 요약만으로 최신 repo나 runtime을 단정한다
코드 존재와 실행 사용 혼동 source에 있는 module을 active method로 착각한다
숫자와 주장 거리 조절 실패 metric 하나를 방법 개선이나 generalization 주장으로 올린다
실패 단계 혼합 data loading, matching, optimization, evaluation 실패를 한 원인으로 합친다
위험 비용 무시 시간, compute, reviewer trust, 원고 주장 범위는 사람이 감당한다

AI가 내놓은 설명을 실행하는 순간부터 비용이 생긴다. 이 구분을 놓치면 연구자는 빠른 답을 얻고도 같은 일을 다시 확인한다.

왜 이런 일이 생기는가

반복 실패는 대체로 작업을 나누는 방식에서 나온다. AI는 대화와 파일 일부를 보고 다음 후보 설명을 만든다. 로보틱스 연구의 상태는 대화 밖에서 바뀐다. Docker container, ROS2 topic, CUDA process, dataset split, calibration file, metric script, TeX table은 실제 파일과 실행 결과로 확인한다.

AI는 텍스트를 빠르게 훑고 나누는 데 강하다. 연구자는 실행과 증거를 확인한다. 이 둘을 섞으면 같은 오류가 반복된다.

섞인 것 반복되는 오류
설명과 원인 그럴듯한 설명을 root cause로 쓴다
코드와 방법 구현되어 있는 코드를 논문 방법으로 쓴다
숫자와 주장 조건이 다른 숫자를 성능 주장으로 쓴다
문장과 답변 reviewer가 요구한 실험 없이 rebuttal 문장만 고친다
요약과 증거 handoff나 memory를 source로 쓴다

이 구분은 AI 도구에서 처음 생긴 문제가 아니다.

Suchman의 Plans and Situated Actions는 Xerox PARC에서 사람들이 복사기를 쓰는 장면에서 출발했다. 시스템이 예상한 절차와 사용자가 실제로 마주한 상황은 자주 어긋났다. 계획은 현장에서 다시 읽히고 고쳐 쓰였다. 연구에서도 prompt와 plan은 확인 지시서에 가깝다. ros2 topic info, CSV, TeX diff, rebuttal table 같은 자료를 보고 나서야 실제 행동을 판단할 수 있다.

Hutchins의 Cognition in the Wild는 해군 함정의 항법을 따라갔다. chart, 도구, 절차, 팀의 말 주고받기가 함께 항로를 만든다. 연구실의 판단도 repo, launch file, dataset, terminal output, paper table, 기억 노트에 흩어져 있다. AI가 말한 연결이 그럴듯해도, 이 자료들을 다시 대조해야 연구 상태를 판단할 수 있다.

Bainbridge의 Ironies of Automation은 자동화 뒤에 operator에게 감시와 비정상 상황 개입이 남는다고 썼다. Parasuraman & Riley는 use, misuse, disuse, abuse를 나누고, 신뢰와 workload가 자동화 사용을 바꾼다고 정리했다. AI가 후보 설명을 빨리 만들수록 연구자는 어느 설명을 실행할지, 어떤 숫자를 원고에 올릴지, reviewer에게 어디까지 말할지 판단해야 한다.

Anthropic의 2026년 Claude Code 사용 분석은 실제 세션에서 사람과 agent가 어떤 결정을 맡았는지 집계했다. 보고서는 사용자가 planning decision의 약 70%를, Claude가 execution decision의 약 80%를 맡는다고 분석했다. 사용자의 전문성은 문제 세팅, 검증 대상 지정, 잘못된 실행 방향 수정에서 드러났다. 연구 작업에서도 이 역할이 커진다.

사용자가 가져오는 것 연구 작업에서의 의미
구체적 문제 세팅 dataset, split, code path, metric, reviewer concern을 정확히 지목한다
검증 지점 지정 어느 config가 runtime에서 읽혔는지 보여 달라고 묻는다
오류 수정 방향 AI가 제안한 원인 중 틀린 stage를 사용자가 걷어낸다

확인할 다섯 줄

AI를 잘 쓰려면 먼저 일을 나눈다.

AI가 만든 설명:
실제로 본 파일:
실행한 명령:
나온 결과:
그 결과로 말할 수 있는 범위:

이 다섯 줄이 있으면 AI의 빠른 탐색을 연구 작업으로 옮길 수 있다. 없으면 답변은 그럴듯해도 다음 세션에서 다시 같은 질문으로 돌아간다. 그 다음 문제는 실제로 본 파일과 나온 결과를 어디에서 복원할지다.

Ch.2 — 현재 상태부터 복원한다

연구 상태를 이어받을 때는 원 파일, 로그, 실행 결과, 생성된 표와 figure부터 본다. 요약은 확인할 위치를 알려 주는 자료다.

Endsley의 situation awareness 모델은 dynamic system에서 상황 인식을 세 단계로 나눈다. 현재 요소를 지각하고, 그 의미를 이해하고, 가까운 미래 상태를 예측하는 일이다. 연구 상태 복원도 이 순서를 따른다. 파일 확인, 실행 맥락 이해, 주장 범위 판단은 서로 다른 일이다.

Maynez et al. 2020은 abstractive summarization 출력에서 입력 문서와 어긋나는 문장을 확인했다. Ji et al. 2022은 NLG hallucination을 원문이나 세계 지식과 어긋나는 생성으로 정리했다. 요약과 기억 기록은 방향을 잡는 자료다. 원 파일과 명령 출력은 다른 무게를 가진다.

증거의 무게

자료 예 말할 수 있는 범위
원 파일 소스 코드, config, TeX, CSV, log 파일 안에서 직접 확인한 내용
실행 결과 command output, generated figure, metric result 해당 실행에서 나온 결과
조건을 확인한 결과 dataset, split, metric, baseline을 확인한 숫자 같은 조건 안의 비교
요약 handoff, compact summary, memory note 다음에 확인할 위치
AI 추정 원인 추정, 구조 해석, 요약 판단 확인해야 할 설명

논문 주장은 원 파일, 실행 결과, dataset, split, metric을 확인한 뒤 확정한다. 명령 출력은 해당 실행의 결과를 말할 수 있다. 방법이 좋아졌다는 문장은 조건 확인 뒤에 쓴다.

복원할 항목

로보틱스 연구 상태는 여러 파일에 흩어져 있다.

상태 확인할 항목
repo branch, commit, modified file, build output
실행 process, container, device, environment, output path
데이터 dataset version, split, sequence, calibration
결과 metric output, plot, table, failed run
원고 TeX diff, figure 원본, table, paragraph
기억 project memory, handoff, durable correction

복원 순서

  1. 현재 repo와 공개/비공개 경계를 확인한다.
  2. project memory나 handoff가 있으면 방향을 잡는 자료로 읽는다.
  3. 원 파일을 찾는다.
  4. 실행 결과가 필요한 경우 command와 output path를 확인한다.
  5. 원고 작업이면 table, figure, paragraph를 함께 본다.
  6. summary와 원 파일이 충돌하면 원 파일을 우선한다.
  7. 다음 행동 하나만 정한다.

예를 들어 final_results.csv가 있어도 command와 config가 없으면 숫자가 있다는 말까지만 할 수 있다. 방법이 좋아졌다는 말에는 dataset, split, metric script, baseline 확인이 필요하다.

공개 문서에는 반복되는 실패 유형, 운영 규칙, 공개용 template만 둔다. 개인 대화 원문, 개인 경로, reviewer 원문, 미공개 숫자, 인증 정보는 로컬 기록에 남긴다.

Ch.3 — 한 번에 하나만 바꾼다

AI 작업은 범위가 쉽게 커진다. 처음에는 log 분석이었는데 중간에 코드 수정이 들어가고, 마지막에는 실험 해석과 원고 문장까지 따라온다. 이렇게 한 번에 여러 상태를 건드리면 무엇이 바뀌었는지 추적하기 어렵다.

ReAct는 reasoning trace와 task-specific action을 번갈아 생성하게 해, Wikipedia API나 환경에서 새 정보를 얻으며 plan을 고치게 했다. Toolformer는 calculator, QA, search, translation, calendar API를 언제 부를지 모델이 학습하게 했다. 두 연구는 모델이 대화 밖의 도구를 쓰게 했다. 연구 작업으로 옮길 때는 tool 호출과 근거의 무게를 나눠야 한다. git diff, ros2 출력, metric CSV, PDF build 결과가 각각 어떤 말을 허용하는지 따로 봐야 한다.

Bainbridge가 지적한 automation 역설은 AI 작업에도 나타난다. 자동화가 쉬운 일을 넘겨받으면 사람은 더 높은 수준의 감시와 개입을 맡는다. 한 번의 AI 작업은 작게 잡는다.

작업 전에 적을 것

비중 있는 작업은 아래 항목을 먼저 둔다.

지금 실제로 본 것:
바꾸려는 대상:
바꿀 수 있는 파일 또는 실행:
결과가 나오면 말할 수 있는 것:
아직 말하면 안 되는 것:
다음에 남길 기록:

여기까지 적으면 작업 범위가 보인다. 확인 범위가 선명할수록 연구 판단도 정확해진다.

자주 나오는 작업 유형

작업 적용 상황
작업 상태 복원 이전 작업을 이어야 할 때
구현 디버깅 코드, Docker, ROS2, runtime 문제가 있을 때
실험 설계 조건을 새로 정할 때
결과 해석 숫자와 표를 해석할 때
논문-실험 연결 논문 주장에 실험을 연결할 때
원고 주장 수리 원고 주장의 근거를 고칠 때
reviewer 답변 심사 의견에 답할 때
관련 연구 정리 novelty와 비교 위치를 잡을 때

실행 권한을 먼저 정한다

작업 방식도 먼저 정한다.

방식 허용되는 행동
읽기만 파일 읽기와 분석만 허용
제안만 구조나 계획 제안만 허용
실행 허용 명령 실행 허용, 파일 수정은 별도 확인
편집 허용 파일 수정 허용
실행 요청 실행과 결과 확인까지 요구

정하지 않으면 AI가 읽어야 할 자리에서 파일을 고치고, 실행해야 할 자리에서 계획만 내놓을 수 있다.

완료 보고는 좁게 쓴다

성공 기준은 다시 확인할 수 있어야 한다. Anthropic의 Claude Code 사용 분석은 judged success와 별도로 verified success를 두고, passing test, matching commit, 목표와 맞는 command output, 사용자의 명시적 확인을 집계했다. 연구 작업에서도 같은 기준을 쓴다.

넓은 보고 더 나은 보고
시스템을 고쳤다 command X 뒤 warning signature Y가 사라졌다
성능이 좋아졌다 같은 조건 P에서 metric M이 baseline B와 비교해 낮아졌다
논문 답변이 준비됐다 Table 2 조건과 response scope를 맞췄다
repo를 이해했다 파일 A/B/C와 남은 질문 D를 확인했다

반복 실패는 다음 세션에서 확인할 규칙으로 바꾼다. 요약을 원본처럼 썼다면 원본 확인 규칙을 남긴다. 코드 존재를 active method로 착각했다면 구현 상태 라벨을 남긴다. reviewer comment를 문장 문제로 처리했다면 주장·근거 표를 남긴다.

Ch.4 — 논문과 코드를 맞춰 본다

논문 요약은 시작일 뿐이다. 로봇 논문을 실제 연구에 쓰려면 논문 문장, 공개 코드, 현재 환경에서 돌릴 실험을 따로 확인해야 한다.

논문 method 문장은 주장을 담고, 공개 코드는 구현 상태를 드러내며, runtime은 현재 환경에서 실제로 나온 결과를 남긴다. 이 셋은 따로 확인한다. NeurIPS 2019 Reproducibility Program 보고서도 결과의 신뢰성을 확인하려면 같은 code와 data, 실행 조건으로 다시 돌려 보는 일이 필요하다고 썼다. 논문에 적힌 component가 repo에 있어도 그 component가 config를 거쳐 실행되고 결과에 영향을 줬는지는 따로 확인해야 한다.

논문을 연구에 쓰려면 abstract 요약 다음에 주장의 실험 조건을 찾는다.

남길 항목

논문 주장:
관련 code path:
실제로 호출되는 경로:
실험 command:
metric script:
비교할 수 있는 범위:

확인할 질문

질문 이유
논문 주장이 어느 table, figure, section에 있는가 원고 주장 범위를 확인한다
공개 코드에서 해당 모듈이 어디 있는가 코드 존재 여부를 확인한다
그 모듈이 실제 예제에서 호출되는가 실행 경로를 확인한다
config key가 runtime에 읽히는가 config만 있고 쓰이지 않는 상태를 막는다
논문 표의 숫자를 만든 script가 공개되어 있는가 재현 가능성을 확인한다
issue나 commit에서 convention이 바뀌었는가 현재 branch의 의미를 확인한다

구현 상태 라벨

코드에 존재한다는 말로는 부족하다. 다음 중 하나로 적는다.

라벨 의미
active runtime에서 호출되고 결과에 영향을 준다
disabled 구현되어 있으나 꺼져 있다
configured-unused config에는 있으나 실행 경로 밖에 있다
planned-only 문서나 issue에만 있다
tested-failed 시도했으나 실패 기록이 있다
dead 남아 있으나 현재 경로 밖에 있다
unknown 확인 전

AI에게는 paper에서 method component를 뽑고, repo에서 관련 function, class, config를 찾고, issue thread와 README의 convention 변화를 모으는 일을 맡기기 좋다. 실제 호출 여부, config가 runtime에 도달하는지, 같은 dataset과 metric 조건인지, 원고에서 어디까지 말할 수 있는지는 실행 결과로 확인한다.

abstract 다음에는 YAML, launch command, issue comment, failed sequence, table caption까지 내려간다.

Ch.5 — 숫자에는 조건이 붙는다

실험 숫자는 조건과 함께 비교한다. 로보틱스 metric은 이름이 같아도 dataset, split, sensor, frame, calibration, alignment, metric script, failure policy, baseline이 다르면 다른 숫자다.

로보틱스 benchmark는 숫자만 두지 않고 evaluation script, dataset protocol, failure policy를 함께 둔다. 낮은 error, 높은 success rate, 빠른 latency를 원고에 쓰려면 그 숫자가 어떤 조건에서 나왔는지 같이 적어야 한다.

최소 기록

dataset:
split:
sequence:
sensor/modality:
task input/output:
ground-truth frame:
alignment:
metric:
threshold:
baseline:
command:
config:
output path:
timeout:
failure policy:

로보틱스 task에서 볼 항목

항목 확인 내용
coverage 입력 구간과 출력 구간이 서로 맞는가
output count 예상 출력 수와 실제 출력 수가 맞는가
timestamp span 시작/종료 시간이 맞는가
frame/calibration frame convention과 calibration이 같은가
preprocessing resize, crop, filtering, normalization 조건이 같은가
cache/checkpoint 현재 model과 config에서 나온 결과물인가
failure policy 실패 구간을 평균이나 집계에서 어떻게 처리했는가

평가 조건에서 볼 항목

항목 확인 내용
task input/output 어떤 입력에서 어떤 출력을 평가하는가
ground truth 정답 파일, 좌표계, 시간 범위가 같은가
threshold success/failure를 가르는 기준이 같은가
baseline 같은 조건의 baseline인가
metric script 지난번과 같은 script인지
output path 실제로 읽은 결과 파일이 맞는지

원고 문장에는 조건을 넣는다.

같은 dataset, 같은 sensor 입력, 같은 metric script를 쓴 baseline 대비 main metric이 개선되었다.

조건이 빠진 문장은 보류한다.

성능이 향상되었다.

표 caption도 같은 규칙을 따른다. metric 표에는 수치와 비교 조건이 있어야 한다. event count 표는 센 횟수만 말한다. downstream task 영향까지 말하려면 추가 근거가 필요하다. 표 아래 한 문장도 표가 직접 보여 준 범위 안에서만 쓴다.

실패도 결과다. timeout, OOM, sensor dropout, tracking lost, missing sequence, metric script failure, invalid ground truth는 다음 실험 조건을 정하는 자료가 된다.

Ch.6 — 실패 지점 찾기

AI는 root cause를 빨리 말한다. QoS, calibration, cache, normalization 같은 단어가 바로 나온다. 도움이 될 때도 있다. 어느 단계에서 신호가 끊겼는지 확인하기 전까지는 후보 설명으로 둔다.

복잡한 로보틱스 pipeline은 단계마다 다른 실패를 낸다. data loading, representation, matching, geometry, optimization, evaluation이 각각 다른 증상을 만든다. Endsley의 situation awareness 모델은 먼저 현재 신호를 지각하고, 그 의미를 이해한 뒤, 다음 상태를 예측하는 순서를 잡았다. 디버깅도 먼저 신호를 보고, 그 신호가 어느 단계에서 나온 것인지 구분한 뒤, 다음 행동을 고른다.

기본 순서

input
preprocessing
representation
matching
geometry
optimization
evaluation

ROS2 callback이 비어 있을 때

수정 전에 다음을 본다.

  1. ros2 topic list로 topic 존재 확인
  2. ros2 topic info --verbose로 QoS 확인
  3. publisher/subscriber namespace 확인
  4. use_sim_time과 /clock 확인
  5. container device, network, volume 확인
  6. 그다음 코드 또는 launch 수정

일반적인 로보틱스 task에서 성능이 갑자기 떨어졌을 때

수정 전에 다음을 본다.

  1. dataset, split, sensor input 범위 확인
  2. timestamp, frame, calibration 확인
  3. preprocessing과 normalization 확인
  4. cache, checkpoint, intermediate output 확인
  5. matching, geometry, optimization의 입력과 출력 확인
  6. metric script와 failure policy 확인
  7. 그다음 model architecture, training 설정, control parameter 수정

기록 형식

각 확인은 같은 형식으로 남긴다.

stage:
command:
workdir:
observed signal:
changed file:
output path:
next stage:

구분해야 할 실패

실패 종류 예
실행 환경 실패 pip install, CUDA driver, Docker volume, dataset path
runtime 실패 callback 없음, tf lookup 실패, node crash
평가 실패 wrong frame, wrong split, wrong metric script
방법 실패 조건을 맞춰 확인한 뒤에도 성능이 낮음

build pass는 소스 컴파일을 확인한다. callback, tf lookup, metric correctness, output validity는 따로 확인한다.

Ch.7 — 주장과 근거를 먼저 본다

AI는 원고 문장을 매끄럽게 만든다. 원고와 답변서에서는 이 능력이 위험해질 수 있다. reviewer comment가 tone, 실험 조건, 주장 범위 중 무엇을 겨냥하는지 먼저 확인한다.

Toulmin의 The Uses of Argument는 실제 논쟁에서 주장이 어떻게 버티는지 분석했다. claim, data, warrant, backing, qualifier, rebuttal은 서로 다른 역할을 맡는다. 논문 답변서에서도 주장은 근거와 보증을 따라간다. reviewer comment는 주로 주장을 받치는 근거와 보증을 묻는다.

답변 전에 볼 것

항목 내용
심사 의견 원문 또는 요약
문제가 된 주장 reviewer가 겨냥한 문장
현재 근거 figure, table, experiment, citation
부족한 근거 새로 필요한 실험 또는 계산
원고 수정 위치 고칠 section, table, caption, paragraph
답변 범위 답변서에서 말할 수 있는 범위
남는 한계 인정해야 할 한계

처리 순서

  1. reviewer comment에서 공격받은 주장을 뽑는다.
  2. 해당 주장이 기대는 table, figure, experiment, citation을 찾는다.
  3. 근거가 충분하면 답변 문장을 쓴다.
  4. 근거가 부족하면 실험, 재계산, 주장 축소 중 하나를 선택한다.
  5. 원고 수정 위치를 답변서에 명시한다.

자주 생기는 실패

실패 결과
comment를 tone 문제로 처리 비교 조건이나 실험 공백이 남는다
robust, general, significant를 추가 근거가 받치지 못하는 주장으로 커진다
citation만 추가 reviewer가 지적한 실험 조건 확인이 빠진다
공손한 문장부터 작성 Table, Figure, Section 수정이 빠진다

표를 고칠 때도 같은 순서다. metric 표에는 낮은 error나 높은 success rate와 함께 dataset, sensor, frame, failure policy가 있어야 비교가 된다. event count 표는 센 횟수를 말한다. downstream task 영향까지 말하려면 precision, outlier rejection, runtime 영향 근거가 필요하다. caption과 본문 문장은 표가 담은 범위 안에서 쓴다.

예의는 필요하다. 정중한 문장은 실험 조건 위에 얹는다. 같은 split과 같은 metric script로 baseline을 다시 맞췄다면 그렇게 쓴다. cross-dataset generalization 근거가 없으면 해당 표현은 줄인다.

Ch.8 — 남의 repo에서 습관만 가져온다

공개 agent repo에는 가져올 습관이 있다. 작은 수정, 가정 명시, 실패 보고, 역할 분리, tool 호출 기록 같은 습관은 연구에도 도움이 된다. 그 규칙을 로봇 연구에 그대로 옮기면 빠지는 항목이 많다.

일반 agent repo는 코드 변경과 tool use에 강하다. 로보틱스 연구에서는 dataset, calibration, frame, metric, 실패 처리, reviewer risk가 실험 숫자의 의미를 정한다.

Anthropic의 Managed Agents는 agent 작업을 session, harness, sandbox로 나누는 방식을 제시했다. 연구 workspace에 옮기면 session은 다음 세션이 다시 읽을 기록이고, harness는 agent가 따라야 할 규칙이며, sandbox는 실제 파일·command·dataset이 있는 실행 경계다. 외부 repo를 가져올 때도 이 세 경계를 먼저 옮긴다. prompt 문구는 그다음에 조정한다.

참고할 repo 유형

유형 예 볼 것
coding-agent skill repo multica-ai/andrej-karpathy-skills 작은 수정, 가정 명시, 범위 제한, 실패 보고
agent 개념 입문 repo datawhalechina/hello-agents agent, memory, tool use, evaluation 항목
framework 문서 LangGraph, CrewAI, AutoGen, OpenAI Agents SDK workflow, role 분리, tool handoff, tracing
local research agent repo alexjunholee/robotics-research-agent user reaction prior, 연구 증거 확인 규칙

그대로 가져오면 빠지는 항목

옮길 때 볼 것

  1. 외부 repo의 규칙을 기능별로 나눈다.
  2. Claude, Cursor, Codex 등 특정 도구에 묶인 호출법을 제거한다.
  3. durable state는 project-memory.json, ledger, replay case로 옮긴다.
  4. 남는 행동 규칙은 AGENTS.md나 template로 옮긴다.
  5. 실제 실행 경계는 repo, dataset, artifact, command로 나눈다.
  6. dataset, metric, 결과물, reviewer risk 항목을 더한다.
  7. 사용자가 반복해서 반려한 패턴을 앞에 둔다.

답변 전에 아래 항목을 확인한다.

읽지 않은 파일을 읽은 것처럼 말했는가:
근거 범위를 넘는 주장을 썼는가:
실행해야 할 때 계획만 말했는가:
사용자가 싫어한 문체나 구조를 반복했는가:
공개 문서에 내부 작업 기록을 남겼는가:

해당 항목이 하나라도 있으면 다음 행동을 바꾼다.

GitHub star 수는 발견할 때만 참고한다. 기준은 연구에서 같은 metric 혼동, 같은 cache 실수, 같은 reviewer comment를 줄일 수 있는지다.

Ch.9 — 로봇은 코드 밖에서 실패한다

로봇 실험에서 먼저 확인할 것

AI 코딩 에이전트(Claude, Copilot, ChatGPT 등)는 일반 소프트웨어 개발에서는 강력한 도구다. 함수 하나 짜달라고 하면 꽤 쓸만한 코드가 나오고, 에러 메시지를 붙여넣으면 원인을 잘 짚어준다. 하지만 로보틱스는 다르다. 하드웨어, OS, 네트워크, 실시간성이 복잡하게 얽혀 있고, "코드는 맞는데 안 되는" 상황이 일상이다. AI는 이런 영역에서 자주 틀리거나, 자신 있게 엉뚱한 방향을 제시하거나, 아예 포기한다.

그래서 질문보다 관측값이 먼저다. topic, device, clock, network, 권한, architecture가 확인되어야 에이전트의 답도 쓸모가 생긴다.

ROS에서 자주 막히는 지점

QoS 설정

AI에게 ROS2 subscriber를 짜달라고 하면 QoS(Quality of Service)를 default(RELIABLE)로 놓는다. 센서 토픽(카메라, LiDAR)은 BEST_EFFORT로 퍼블리시되는 경우가 대부분인데, subscriber가 RELIABLE이면 데이터가 아예 안 들어온다. 에러 메시지도 안 뜨고 그냥 조용히 안 되니까, AI는 "토픽이 없나?" 하고 엉뚱한 방향으로 디버깅을 시작한다.

# 토픽의 QoS 프로파일 확인
ros2 topic info /camera/image_raw --verbose

출력에서 Reliability: BEST_EFFORT, Durability: VOLATILE 같은 정보를 확인하고, subscriber의 QoS를 맞춰야 한다.

from rclpy.qos import QoSProfile, ReliabilityPolicy, DurabilityPolicy

qos = QoSProfile(
    reliability=ReliabilityPolicy.BEST_EFFORT,
    durability=DurabilityPolicy.VOLATILE,
    depth=10
)
self.subscription = self.create_subscription(Image, '/camera/image_raw', self.callback, qos)

AI에게 코드를 요청할 때는 "이 토픽의 QoS는 BEST_EFFORT / SENSOR_DATA다"라고 명시적으로 알려줘야 한다. 안 그러면 기본값으로 만들어서 데이터가 안 들어오는데, AI는 원인을 못 찾는다.

use_sim_time과 tf2 타이밍

rosbag 재생 시 use_sim_time:=true를 안 하면 tf lookup이 전부 실패한다. AI는 "tf2 lookup failed" 에러를 보면 static_transform_publisher를 추가하라고 한다. 엉뚱한 방향이다.

실제 원인은 시뮬레이션 클럭과 시스템 클럭의 불일치다. bag 파일의 타임스탬프는 과거 시점인데, 노드는 현재 시스템 시간을 기준으로 tf를 조회하니까 당연히 못 찾는다.

# 올바른 rosbag 재생
ros2 bag play my_bag --clock

# 노드 실행 시 sim_time 활성화
ros2 launch my_package my_launch.py use_sim_time:=true

tf2 lookup에는 timeout과 try/except가 필요한데, AI는 이걸 빠뜨린다.

from rclpy.duration import Duration

try:
    transform = tf_buffer.lookup_transform(
        'base_link', 'camera_link',
        rclpy.time.Time(),
        timeout=Duration(seconds=1.0)
    )
except tf2_ros.LookupException as e:
    self.get_logger().warn(f'TF lookup failed: {e}')

Workspace 소싱 순서

ROS2 workspace의 소싱 순서가 중요하다. /opt/ros/humble/setup.bash를 먼저 source하고, 그다음에 ~/ros2_ws/install/setup.bash를 source해야 한다. AI는 하나만 source하거나 순서를 뒤집는다. overlay workspace 개념을 아예 모르는 경우도 있다.

# 올바른 순서
source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/setup.bash

.bashrc에 넣었는데 새 터미널에서 패키지를 못 찾으면, AI는 패키지 재설치를 권한다. source 문제다. echo $AMENT_PREFIX_PATH로 현재 소싱된 workspace를 확인하자.

커스텀 메시지와 빌드

AI는 .msg 파일은 잘 만든다. 하지만 CMakeLists.txt와 package.xml의 의존성 추가를 빠뜨린다.

rosidl_generate_interfaces 설정이 빠지면 빌드는 되는데 Python에서 import할 때 실패한다. 이 에러가 나면 AI는 "패키지가 설치 안 됐다"고 오진하기 쉽다.

# CMakeLists.txt에 반드시 추가
find_package(rosidl_default_generators REQUIRED)

rosidl_generate_interfaces(${PROJECT_NAME}
  "msg/MyCustomMsg.msg"
  DEPENDENCIES std_msgs geometry_msgs
)

<!-- package.xml에 반드시 추가 -->
<buildtool_depend>rosidl_default_generators</buildtool_depend>
<exec_depend>rosidl_default_runtime</exec_depend>
<member_of_group>rosidl_interface_packages</member_of_group>

또 하나: --symlink-install 없이 빌드하면 Python 코드 수정이 반영되지 않는다. AI는 이걸 "캐시 문제"라고 오진한다.

# Python 패키지 수정이 바로 반영되려면
colcon build --symlink-install

네임스페이스와 리매핑

ros2 topic echo /camera/image_raw 했는데 데이터가 안 오면, AI는 드라이버 문제라고 진단한다. 네임스페이스 때문에 토픽 이름이 /robot1/camera/image_raw일 수 있는데도.

# 토픽 목록부터 확인하라
ros2 topic list

# 특정 패턴으로 필터링
ros2 topic list | grep camera

AI에게 디버깅을 시킬 때는 ros2 topic list와 ros2 node list 출력을 먼저 제공해야 한다. 이 정보 없이 "토픽이 안 들어와요"라고 하면 AI는 추측으로 답할 수밖에 없다.

Launch 파일

AI가 ROS2 Python launch 파일을 쓸 때 반복적으로 하는 실수들:

# multi-robot launch 파일에서 네임스페이스 적용
from launch.actions import GroupAction, PushRosNamespace

robot1_group = GroupAction([
    PushRosNamespace('robot1'),
    Node(package='my_pkg', executable='my_node', name='sensor_node'),
])

AI에게 launch 파일을 요청할 때는 "ROS2 Python launch 파일", "multi-robot이면 네임스페이스 적용", "ComposableNode 사용 여부" 등을 명시해야 한다.

Docker에서 자주 빠지는 설정

GUI/시각화 문제

Docker 안에서 RViz나 Gazebo 같은 GUI 도구를 띄우려면 X11 포워딩이 필요하다. AI는 xhost +local:docker를 권하는데, 이는 모든 로컬 연결에 X 서버 접근을 허용하는 것이라 보안상 위험하다.

제대로 하려면 다음과 같이 설정한다:

docker run -it \
  --env DISPLAY=$DISPLAY \
  --env QT_X11_NO_MITSHM=1 \
  -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
  --ipc=host \
  my_image

각 옵션의 역할: - QT_X11_NO_MITSHM=1 — AI는 이 옵션을 거의 모른다. 없으면 RViz가 segfault로 죽는다. MIT-SHM(공유 메모리) 확장이 Docker 환경에서 제대로 동작하지 않기 때문이다. - --ipc=host — 호스트와 IPC 네임스페이스를 공유한다. 없으면 shared memory 문제로 시각화 도구가 죽는 경우가 많다. - Wayland 환경(Ubuntu 22.04+ 기본)에서는 X11 소켓 마운트만으로 안 되는 경우가 있다. XDG_SESSION_TYPE=x11로 X11 세션을 강제하거나, XWayland를 거쳐야 할 수 있다.

USB 디바이스 패스스루

카메라, LiDAR, IMU 등 USB 장치를 Docker 안에서 쓰려면 디바이스를 명시적으로 매핑해야 한다. AI는 이걸 모르고 "드라이버 설치하라"고 한다.

# 특정 디바이스만 매핑 (권장)
docker run -it --device=/dev/ttyUSB0 --device=/dev/video0 my_image

# 모든 디바이스 접근 허용 (보안상 비추, 디버깅용으로만)
docker run -it --privileged my_image

--privileged는 편하지만 컨테이너에 호스트의 거의 모든 권한을 주는 것이므로, 프로덕션에서는 필요한 device만 매핑하는 게 맞다.

한 가지 더: USB 장치가 Docker 컨테이너 시작 후에 꽂히면 인식이 안 된다. AI는 이 상황을 전혀 고려하지 못한다. 컨테이너를 재시작하거나, --privileged + -v /dev:/dev 조합을 써야 한다.

ROS 네트워킹

Docker 컨테이너 간 ROS2 통신에서 --network=host가 가장 간단하지만, 호스트의 포트를 전부 공유하므로 포트 충돌 위험이 있다.

AI는 bridge 네트워크에서 ROS2가 왜 안 되는지 설명하지 못한다. 원인은 DDS(Data Distribution Service)가 multicast를 사용하는데, Docker bridge 네트워크에서는 multicast가 기본적으로 안 되기 때문이다.

# 가장 간단한 방법 (개발 환경에서)
docker run -it --network=host my_ros2_image

# ROS_DOMAIN_ID로 다른 사람과 충돌 방지
docker run -it --network=host -e ROS_DOMAIN_ID=42 my_ros2_image

ROS_DOMAIN_ID가 같은 네트워크의 다른 사람 ROS2와 충돌할 수 있다. 연구실에서 여러 명이 동시에 ROS2를 쓰면 서로의 토픽이 보이는 상황이 생긴다.

DDS 설정을 세밀하게 해야 할 때는 Cyclone DDS config XML로 특정 네트워크 인터페이스만 사용하게 제한한다:

<!-- cyclone_dds.xml -->
<CycloneDDS>
  <Domain>
    <General>
      <NetworkInterfaceAddress>eth0</NetworkInterfaceAddress>
    </General>
  </Domain>
</CycloneDDS>

export CYCLONEDDS_URI=file:///path/to/cyclone_dds.xml

파일 권한 문제

Docker 안에서 생성된 파일은 기본적으로 root 소유다. 호스트에서 편집하거나 삭제하려면 sudo가 필요하다.

# 호스트 유저 권한으로 실행
docker run -it --user $(id -u):$(id -g) my_image

하지만 일부 ROS 패키지가 root 권한을 필요로 해서 --user 옵션을 쓰면 또 안 되는 경우가 있다. AI는 이런 상황에서 chmod 777을 남발하는데, 실무에서는 이러면 안 된다. Dockerfile에서 non-root 유저를 만들고 필요한 디렉토리 권한만 설정하는 것이 올바른 방법이다.

# Dockerfile에서 non-root 유저 설정
RUN useradd -m -s /bin/bash rosuser && \
    usermod -aG dialout rosuser
USER rosuser

하드웨어와 드라이버 신호

시리얼 포트 권한

/dev/ttyUSB0 접근 시 Permission denied가 뜨면, AI는 sudo chmod 666 /dev/ttyUSB0을 권한다. 되긴 되지만, 재부팅하면 리셋된다. 매번 이걸 치고 있을 수는 없다.

올바른 방법은 udev rule을 작성하는 것이다:

# 벤더/프로덕트 ID 확인
udevadm info -a -n /dev/ttyUSB0 | grep -E 'idVendor|idProduct'

# /etc/udev/rules.d/99-sensors.rules
SUBSYSTEM=="tty", ATTRS{idVendor}=="1546", ATTRS{idProduct}=="01a9", MODE="0666", SYMLINK+="gps"

# udev rule 적용
sudo udevadm control --reload-rules && sudo udevadm trigger

이렇게 하면 해당 USB 장치가 항상 /dev/gps라는 고정 이름으로 잡히고, 권한도 자동으로 설정된다. 여러 개의 동일 장치를 구분해야 할 때(예: IMU 2개)도 시리얼 넘버로 구분할 수 있다. AI는 udev를 모른다.

USB 대역폭

USB3 카메라 3대를 같은 USB 허브에 꽂으면 대역폭 부족으로 프레임 드롭이 발생한다. AI는 "드라이버 업데이트하라" 또는 "해상도를 낮춰라"고 하지만, 실제 원인은 USB 컨트롤러의 대역폭 한계다.

# 어떤 카메라가 어떤 USB 컨트롤러에 붙어있는지 확인
lsusb -t

이 문제는 소프트웨어로 해결할 수 없다. 물리적으로 다른 USB 컨트롤러에 카메라를 분산 연결해야 한다. 데스크탑 PC의 앞면 USB와 뒷면 USB는 다른 컨트롤러에 연결된 경우가 많으니, lsusb -t의 Bus 번호를 확인하고 분산 배치하자.

LiDAR 연결 (IP 설정)

Velodyne이나 Ouster LiDAR에서 "데이터가 안 온다"는 문제의 90%는 네트워크 설정이 원인이다. AI는 드라이버 재설치나 ROS 패키지 재빌드를 권하지만, 그 전에 확인해야 할 것이 있다.

LiDAR는 고정 IP(예: 192.168.1.201)를 사용한다. 호스트 PC의 이더넷 인터페이스를 같은 서브넷(예: 192.168.1.100)으로 설정해야 통신이 된다.

# 1단계: LiDAR에 ping이 되는지 확인
ping 192.168.1.201

# 2단계: 호스트 이더넷 인터페이스 IP 설정
sudo ip addr add 192.168.1.100/24 dev eth0
sudo ip link set eth0 up

# 3단계: UDP 패킷이 오는지 Wireshark로 확인
sudo tcpdump -i eth0 udp port 2368 -c 10

ping부터 해보면 대부분 여기서 걸린다. Wireshark(또는 tcpdump)로 UDP 패킷이 오는지 확인하는 게 가장 확실한 디버깅 방법이다. 패킷이 오는데 ROS에서 안 보이면 그때 드라이버를 의심해도 늦지 않다.

카메라 드라이버 (v4l2)

AI는 cv2.VideoCapture(0)만 알지, /dev/video*가 여러 개일 때 어떤 게 실제 카메라인지 구분하지 못한다. USB 카메라 하나를 꽂아도 /dev/video0, /dev/video1이 생기는 경우가 흔한데(metadata용 디바이스), AI는 이걸 모른다.

# 카메라 디바이스 매핑 확인
v4l2-ctl --list-devices

# 지원하는 포맷과 해상도 확인
v4l2-ctl -d /dev/video0 --list-formats-ext

자동 노출(auto exposure), 자동 화이트밸런스 — 이런 자동 설정이 SLAM 성능을 망치는 경우가 많다. 밝기가 계속 변하면 특징점 추출이 불안정해진다.

# 수동 노출 설정 (SLAM용)
v4l2-ctl -d /dev/video0 --set-ctrl=exposure_auto=1
v4l2-ctl -d /dev/video0 --set-ctrl=exposure_absolute=100

# 화이트밸런스 고정
v4l2-ctl -d /dev/video0 --set-ctrl=white_balance_automatic=0

AI는 이런 low-level 카메라 제어를 모른다. "SLAM이 불안정하다"고 하면 알고리즘 파라미터 튜닝을 권하지만, 카메라 자동 설정을 끄는 것만으로 크게 개선되는 경우가 있다.

Jetson (ARM) 환경

AI가 생성한 코드나 Docker 설정은 x86 기준이다. NVIDIA Jetson(ARM64)에서는 안 돌아가는 경우가 많다.

주의해야 할 점: - pip install로 설치할 때 pre-built 바이너리(wheel)가 ARM용으로 없는 패키지가 많다. 특히 scipy, opencv-python은 소스에서 빌드해야 해서 수십 분이 걸린다. - JetPack 버전에 따라 CUDA, cuDNN, TensorRT 버전이 고정된다. AI가 최신 버전을 설치하라고 권하면 전체 시스템이 꼬인다. - Docker를 쓸 때는 NVIDIA에서 제공하는 l4t(Linux for Tegra) 기반 이미지를 써야 한다.

# Jetson에서 Docker 이미지 — x86 이미지 쓰면 안 된다
docker pull nvcr.io/nvidia/l4t-pytorch:r35.2.1-pth2.0-py3

# JetPack 버전 확인
cat /etc/nv_tegra_release

AI에게 코드를 요청할 때는 "Jetson Orin, JetPack 5.1.2, CUDA 11.4 환경이다"라고 명시해야 한다.

실시간 제어와 타이밍

AI는 time.sleep(0.01)로 100Hz 루프를 만들라고 하지만, 정확하지 않다. time.sleep()의 정밀도는 OS 스케줄러에 의존하며, 일반 Linux 커널에서는 수 밀리초의 jitter가 발생한다.

# AI가 주로 권하는 방법 (정확하지 않음)
import time
while True:
    do_control()
    time.sleep(0.01)  # 실제로는 10~15ms가 될 수 있다

Python의 GIL(Global Interpreter Lock) 때문에 멀티스레드 타이밍은 더 보장이 안 된다. 진짜 실시간 제어가 필요하면 C++과 RT(Real-Time) 커널(PREEMPT_RT)을 써야 한다.

# 실제 퍼블리시 주파수 확인 — 항상 이걸로 검증하라
ros2 topic hz /cmd_vel

AI가 "100Hz로 제어하면 된다"고 해도, ros2 topic hz로 실제 주파수를 확인해야 한다. 기대한 주파수와 실제 주파수가 다르면 제어가 제대로 안 된다.

반복해서 막히는 패턴

"It works in simulation"

Gazebo에서 잘 되는데 실제 로봇에서 안 되는 상황. AI는 "시뮬레이션에서 되니까 코드는 맞고 하드웨어 문제"라고 결론 낸다. 실제 원인은 sim-to-real gap이다:

AI에게는 "시뮬레이션에서는 되는데 실제 로봇에서 안 된다. 센서 노이즈 수준은 X이고, 통신 지연은 Y ms이고, 좌표계 캘리브레이션은 Z 방법으로 했다"처럼 sim-to-real의 차이를 구체적으로 알려줘야 한다.

하드웨어 문제를 소프트웨어로 고치려 함

케이블 불량, 접촉 불량, 전원 부족 — AI는 이런 물리적 문제를 진단할 수 없다.

"센서 데이터가 간헐적으로 끊긴다"고 하면 AI는 버퍼 크기 조절, 타임아웃 설정, QoS 변경 등을 권한다. USB 케이블이 느슨하거나 USB 허브의 전원이 부족한 것인데도.

# 커널 로그에서 하드웨어 문제 단서 찾기
dmesg | tail -20

# USB 연결 해제/재연결 이벤트 확인
dmesg | grep -i usb | tail -20

dmesg에 USB disconnect, device descriptor read/64, error -71 같은 메시지가 보이면 소프트웨어 문제가 아니다. 케이블을 교체하거나, 유전원 USB 허브를 쓰거나, 다른 포트에 꽂아보는 게 먼저다.

환경 문제 진단 포기

라이브러리 버전 충돌이 복잡하게 얽히면 AI는 "전부 재설치하라"고 한다. pip show package_name으로 버전을 확인하고 어떤 것이 충돌하는지 좁히는 게 먼저다.

특히 OpenCV 관련 충돌은 로보틱스의 클래식이다:

이 네 가지가 동시에 설치되면 서로 충돌한다.

# 현재 설치된 OpenCV 확인
pip show opencv-python opencv-python-headless opencv-contrib-python

# 해결: ROS 환경에서는 pip opencv를 설치하지 않는다
pip uninstall opencv-python opencv-python-headless opencv-contrib-python
sudo apt install ros-humble-cv-bridge

ROS 환경에서는 apt install ros-humble-cv-bridge만 쓰고, pip으로 opencv를 따로 설치하지 않는 것이 가장 깔끔하다.

"2-3번 시도 후 포기"

AI는 같은 접근을 두세 번 반복하다 안 되면 "다른 방법을 시도해 보세요"라며 넘긴다. 엔지니어는 여기서 포기하지 않는다. 로그를 뒤지고, strace를 걸고, 패킷을 캡처한다.

더 나은 답을 얻으려면, 에러 메시지뿐 아니라 low-level 정보를 함께 줘야 한다:

# 시스템 로그
dmesg | tail -30
journalctl -u my_service --since "5 minutes ago"

# 프로세스 추적
strace -f -e trace=open,read,write ros2 run my_pkg my_node 2>&1 | head -100

# 네트워크 패킷 캡처
sudo tcpdump -i eth0 -w capture.pcap

이런 정보를 AI에게 제공하면, "재설치하세요" 대신 실제 원인에 가까운 답을 받을 수 있다.

에이전트에게 줄 정보

논문 읽기와 글쓰기에서 에이전트를 쓰는 법은 「연구노트」 Ch.7 — 논문을 세 번에 나누어 읽기 + 「연구노트」 Ch.16 — 마음가짐 에서 다룬다. 여기서는 코드와 하드웨어 쪽 입력을 본다.

컨텍스트를 충분히 제공하라

AI에게 질문할 때 가장 중요한 것은 컨텍스트의 양과 질이다.

틀린 예: "카메라가 안 돼요"

맞는 예: "Ubuntu 22.04, ROS2 Humble, Intel RealSense D435, rs-enumerate-devices에서는 보이는데 ros2 launch realsense2_camera rs_launch.py하면 Could not open device 에러가 난다. Docker 안에서 실행 중이고, --device=/dev/video0은 매핑했다."

AI에게 제공해야 할 정보 체크리스트: - OS 버전, ROS 버전 - 하드웨어 플랫폼 (x86 vs ARM/Jetson) - 센서 모델명 - 에러 메시지 전문 (일부만 복사하지 말고 전체를 줘라) - ros2 topic list, ros2 node list 출력 - Docker 사용 여부와 실행 옵션 (docker run 명령 전체) - 네트워크 구성 (유선/무선, IP 대역)

AI의 답을 검증하는 방법

AI의 답을 그대로 실행하기 전에 다음을 확인하라:

AI가 잘하는 것과 약한 것

AI가 잘하는 것 AI가 못하는 것
알고리즘 구현 (SLAM, detection 등) 하드웨어 디버깅
ROS2 노드/서비스 코드 작성 QoS/DDS 설정 최적화
Python/C++ 코드 리팩토링 USB/시리얼 권한 문제
논문 읽기/요약 네트워크 설정 (LiDAR IP 등)
CMakeLists.txt 작성 실시간 타이밍 문제
데이터 전처리 파이프라인 Docker 안에서의 하드웨어 접근
시각화 코드 (matplotlib, Open3D) 센서 간 시간 동기화 실전
에러 메시지 해석 (일반적인) dmesg/커널 로그 기반 디버깅

AI는 "순수 소프트웨어" 영역에서는 강하지만, 하드웨어와 소프트웨어가 만나는 경계에서 약하다. 로보틱스 문제의 대부분이 그 경계에서 발생한다. AI가 강한 영역은 맡기고, AI가 약한 영역에서는 직접 디버깅한 결과를 AI에게 먹여서 분석하게 하는 게 맞다.

연구 루틴에 붙이는 법

로보틱스 연구자의 하루 일과에서 AI가 어디에 쓰이는지 구체적으로 본다.

논문 읽기

논문 읽기 워크플로우 (3-pass + AI layer cameo)는 「연구노트」 Ch.7 — 논문을 세 번에 나누어 읽기 의 AI layer cameo에서 본격 다룬다.

분야 적용은 분야 핵심 논문에 3-pass + AI summary 결합 — abstract 읽고 contribution 3줄 요청, Eq. 단계별 유도 요청.

코드 작성

실험 설계

실험 설계·ablation·결과 해석에 AI 부려먹기 frame은 「연구노트」 Ch.32 — Revision/Rebuttal (또는 「연구노트」 Ch.27 — Figures) 에 cameo로 담겼다.

분야 적용은 baseline 비교 표를 AI에게 던지고 내가 놓친 비교 축을 묻는 워크플로우.

논문 쓰기

일상 워크플로우 예시

하루 일과에서 AI를 어떻게 쓰는지 구체적 시나리오:

09:00 — 새 논문 3편 arXiv에서 확인. AI에게 각각 1문장 요약 요청
09:30 — 흥미로운 1편 선택, 2패스 읽기. 모르는 수식은 AI에게 유도 요청
10:30 — 어제 학습 결과 분석. loss curve 캡처해서 AI에게 "이 패턴이 정상인가?" 확인
11:00 — 새 실험 코드 작성. AI에게 DataLoader 구조 생성 시킴. 수동으로 augmentation 로직 수정
14:00 — SLAM 코드 디버깅. ROS2 에러 → topic과 QoS 출력으로 원인 좁히기
16:00 — 논문 Related Work 섹션 초고. AI에게 비교 논문 5편의 차이점 표 만들게 시킴
17:00 — 표 검증. AI가 2편의 method를 혼동한 것 발견, 수동 수정

부록 A — 헷갈리기 쉬운 말들

AI 도구를 연구에 쓰면 단어가 쉽게 섞인다. model, tool, agent, memory를 같은 종류로 부르면 실험 숫자와 원고 주장까지 흔들린다. 자주 헷갈리는 말을 구분하기 위한 최소 기준은 아래와 같다.

기본 용어

용어 뜻 조심할 점
모델 텍스트, 코드, 이미지, 표를 생성하거나 판단하는 기반 모델 모델 답변은 현재 workspace 상태를 확인할 출발점이다
도구 파일 읽기, 명령 실행, 검색, 이미지 생성처럼 모델 밖에서 일어나는 행동 도구 결과는 해당 명령이나 API 범위 안에서만 근거가 된다
에이전트 모델과 도구를 묶어 여러 단계를 수행하는 실행자 에이전트가 행동해도 연구 주장은 실행 결과가 정한다
스킬 특정 상황에서 에이전트가 따를 절차와 판단 기준 스킬을 쓸 조건은 작업자가 확인한다
하네스 상태, 근거, 행동, 확인, 주장을 연결하는 운영 구조 한 번의 AI 작업이 어디까지 말할 수 있는지 제한한다
AGENTS.md 에이전트가 작업 전에 읽는 repo 규칙 한 번의 prompt 뒤에도 남는 프로젝트 규칙이다
기억 기록 현재 상태, 반복 위험, 사용자의 durable correction을 보관하는 기록 다시 볼 위치를 알려 주는 자료다
변경 이력 실험, 주장, correction, 반복 확인의 변경 기록 다음 행동을 제한할 때 의미가 있다
반복 확인 같은 실패가 다시 나는지 확인하는 작은 시험 반복 실수를 다음 작업 전에 잡기 위해 쓴다
실험 조건 dataset, split, metric, baseline, output path를 확인한 조건 숫자는 이 조건 안에서만 비교한다
결과물 파일, 로그, 표, figure, checkpoint, command output 출처와 함께 읽어야 한다
주장 원고, 답변서, README, 발표에서 독자에게 믿게 하는 말 근거 범위를 넘으면 안 된다

근거의 무게

단계 예 말할 수 있는 범위
방향 잡기 이전 요약, memory, handoff note 어디를 다시 볼지 정한다
확인 대상 파일명, issue 제목, 검색 결과 원인이나 다음 확인 대상을 제안한다
관찰 원 파일 일부, 로그 일부, config 일부 본 범위 안의 사실을 말한다
실행 결과 명령 실행 결과, 생성된 파일 그 실행의 결과를 말한다
실험 조건 확인 dataset, split, metric, baseline, output path를 확인한 숫자 같은 조건 안에서 비교한다
원고 주장 figure, table, citation, reviewer risk를 함께 확인한 문장 원고와 rebuttal에 쓴다

AI가 자주 틀리는 곳은 이 단계를 건너뛰는 자리다. 요약을 근거처럼 쓰거나, 실행 결과 하나를 방법 개선처럼 말하거나, 일부 로그를 전체 run의 원인처럼 말한다.

도구별로 볼 것

도구 좋은 용도 확인할 항목
Chat model 개념 정리, 논문 질문, 주장 분리 원 파일을 봤는지 구분한다
Coding agent repo 읽기, 작은 수정, script 실행 원 파일, 명령 출력, diff를 남긴다
IDE assistant 한 파일 안의 짧은 편집과 rename 변경 범위와 formatter/test를 확인한다
Browser/search tool 외부 repo, 논문, 문서 발견 링크, 확인일, 주장 범위를 남긴다
Terminal/script build, metric 산출, checksum 확인 실행 command와 output path를 남긴다
Project memory durable correction과 현재 상태 보관 기억 기록은 증거 위치를 찾는 단서로 쓴다

도구를 바꾸면 근거의 무게도 다시 본다. 검색 결과는 후보이고, terminal 실행은 실행 결과다. 숫자는 dataset, split, metric script를 확인한 뒤 원고에 올린다.

Claude 규칙을 Codex에서 쓸 때

Claude용 규칙을 Codex에서 쓸 때는 행동 규칙과 확인 기준만 옮긴다.

Claude 중심 자료 옮길 것 그대로 두면 안 되는 것
CLAUDE.md 행동 규칙, 확인 기준, project boundary Claude-only 명령
.claude/skills 절차 지식, routing rule 파일 경로와 UI 전제
Slash command 반복 가능한 목적과 입력 형식 특정 도구의 호출 문법
Cursor rule 편집 원칙, 문체 점검 editor 내부 설정을 전체 규칙처럼 쓰는 것

Codex에서는 AGENTS.md, templates/, project memory가 이식된 규칙을 받는다. 이식 후에는 빠진 확인 항목을 따로 점검한다.

부록 B — 빠른 시작 파일

본문을 읽은 뒤 새 연구 workspace에 옮길 파일을 정리한다. AI가 잘하는 일과 자주 틀리는 일, 사람이 감당하는 위험, 하네스가 확인하는 경계를 먼저 이해하고 그다음 이 부록을 본다.

도구 역할을 먼저 나눈다

처음에는 연구 상태와 도구 역할을 함께 정한다. 모델명은 그다음 문제다.

연구 장면 먼저 열 도구 첫 확인
repo를 읽고 작은 수정을 한다 coding agent AGENTS.md와 원 파일을 먼저 읽었는가
논문 주장을 code와 experiment에 연결한다 chat model 또는 coding agent 논문-코드-실험 표가 남는가
ROS2, Docker, CUDA, dataset 오류를 좁힌다 coding agent와 terminal stage별 command output이 있는가
외부 repo나 논문을 찾는다 browser/search tool 출처 URL과 주장 범위가 분리됐는가
원고와 답변서를 고친다 manuscript operator role 쓸 문장과 보류할 문장이 분리됐는가
반복 실패를 막는다 harness operator role 변경 기록이나 반복 확인 사례로 남겼는가

같은 AI 제품이 여러 역할을 할 수 있다. 한 turn 안에서 역할이 바뀌면 확인 기준도 다시 적는다.

Workspace를 나눈다

처음에는 단순하게 둔다.

workspace/
├── AGENTS.md
├── README.md
├── project-memory.json
├── repos/
├── datasets/
├── artifacts/
├── notes/
└── templates/

동기화 폴더, 외장 디스크, 원격 서버를 쓰면 git metadata와 dataset 저장 위치를 먼저 정한다. 코드 이력, raw data, 실험 결과물, 비공개 메모는 처음부터 나눠 둔다.

새 workspace를 처음 만들 때는 공개 번들에서 다음 파일을 먼저 복사한다.

공개 번들 새 workspace
templates/workspace-readme.md README.md
templates/AGENTS.template.md AGENTS.md
templates/project-memory.template.json project-memory.json
templates/*.md templates/
필요한 research loop template notes/

번들을 내려받아 풀어 둔 상태라면 다음처럼 시작할 수 있다. GUIDE는 이 가이드 bundle의 루트, WORKSPACE는 새 연구 workspace 위치다.

GUIDE="$PWD"
WORKSPACE="$HOME/robotics-ai-workspace"
mkdir -p "$WORKSPACE"/repos "$WORKSPACE"/datasets "$WORKSPACE"/artifacts \
  "$WORKSPACE"/notes "$WORKSPACE"/templates
cp "$GUIDE/templates/workspace-readme.md" "$WORKSPACE/README.md"
cp "$GUIDE/templates/AGENTS.template.md" "$WORKSPACE/AGENTS.md"
cp "$GUIDE/templates/project-memory.template.json" "$WORKSPACE/project-memory.json"
cp "$GUIDE/templates/"*.md "$WORKSPACE/templates/"
cp "$GUIDE/templates/first-day-workspace-checklist.md" "$WORKSPACE/notes/"
cp "$GUIDE/templates/first-ai-session-prompt.md" "$WORKSPACE/notes/"
cp "$GUIDE/templates/paper-code-experiment-map.md" "$WORKSPACE/notes/"
cp "$GUIDE/templates/experiment-contract.md" "$WORKSPACE/notes/"
cp "$GUIDE/templates/weekly-research-ledger.md" "$WORKSPACE/notes/"

Windows PowerShell에서는 같은 작업을 이렇게 한다.

$Guide = (Get-Location).Path
$Workspace = "$HOME\robotics-ai-workspace"
New-Item -ItemType Directory -Force -Path `
  "$Workspace\repos", "$Workspace\datasets", "$Workspace\artifacts", `
  "$Workspace\notes", "$Workspace\templates" | Out-Null
Copy-Item "$Guide\templates\workspace-readme.md" "$Workspace\README.md"
Copy-Item "$Guide\templates\AGENTS.template.md" "$Workspace\AGENTS.md"
Copy-Item "$Guide\templates\project-memory.template.json" "$Workspace\project-memory.json"
Copy-Item "$Guide\templates\*.md" "$Workspace\templates\"
Copy-Item "$Guide\templates\first-day-workspace-checklist.md" "$Workspace\notes\"
Copy-Item "$Guide\templates\first-ai-session-prompt.md" "$Workspace\notes\"
Copy-Item "$Guide\templates\paper-code-experiment-map.md" "$Workspace\notes\"
Copy-Item "$Guide\templates\experiment-contract.md" "$Workspace\notes\"
Copy-Item "$Guide\templates\weekly-research-ledger.md" "$Workspace\notes\"

복사 직후에는 workspace 루트에서 첫 실행 전 확인을 한다. POSIX shell에서는 다음 항목만 통과하면 첫 AI 세션을 열 수 있다.

cd "$WORKSPACE"
test -f AGENTS.md
test -f README.md
test -f project-memory.json
python3 -m json.tool project-memory.json >/dev/null
test -f notes/first-day-workspace-checklist.md
test -f notes/first-ai-session-prompt.md
test -f notes/paper-code-experiment-map.md
test -f notes/experiment-contract.md
mkdir -p artifacts

Windows PowerShell에서는 같은 확인을 이렇게 한다.

Set-Location $Workspace
@(
  "AGENTS.md",
  "README.md",
  "project-memory.json",
  "notes\first-day-workspace-checklist.md",
  "notes\first-ai-session-prompt.md",
  "notes\paper-code-experiment-map.md",
  "notes\experiment-contract.md"
) | ForEach-Object {
  if (-not (Test-Path $_)) { throw "missing $_" }
}
Get-Content .\project-memory.json | ConvertFrom-Json | Out-Null
New-Item -ItemType Directory -Force -Path .\artifacts | Out-Null

project-memory.json에는 다섯 묶음이 있어야 한다. source_of_truth는 AI가 다시 읽을 파일을 가리키고, tool_surface_map은 연구 장면별 도구 역할을 나눈다. current_evidence는 지금 쓸 수 있는 말과 보류할 말을 분리한다. first_research_loop는 처음 열 루프 하나만 고정하고, next_smallest_actions는 다음 세션의 첫 행동을 남긴다.

여기서는 Anthropic의 Managed Agents에서 말한 session, harness, sandbox 분리를 연구 workspace에 옮긴다. project-memory.json과 ledger는 session이고, AGENTS.md와 prompt template은 harness이며, repo·dataset·artifact·command는 sandbox다. 첫 AI 세션은 이 세 경계를 먼저 말한 뒤 하나의 행동만 골라야 한다.

그다음 notes/first-ai-session-prompt.md의 Prompt To Send 블록에서 빈칸을 채우고 artifacts/first-ai-session-message.txt에 저장한다. 첫 AI 세션에는 이 파일을 그대로 넣는다.

AGENTS.md 작성

templates/workspace-readme.md를 README.md로 복사하고, 프로젝트 이름과 repo, dataset, artifact 위치만 채운다. 그다음 templates/AGENTS.template.md에서 다음 항목만 먼저 채운다.

이미 CLAUDE.md, .claude/, Cursor rule이 있으면 templates/codex-porting-checklist.md로 옮길 규칙과 버릴 명령을 나눈다. 파일 이름과 plugin 명령은 도구별 형식이다. 먼저 규칙의 의미를 본다. assumption을 드러내라, 작게 고쳐라, 성공 기준을 검증 가능하게 만들어라 같은 규칙은 Codex에서도 그대로 쓴다.

첫 상태 체크리스트를 채운다

templates/first-day-workspace-checklist.md는 현재 연구 상태의 원 파일과 실행 결과를 정한다.

project goal:
code truth:
dataset truth:
experiment truth:
manuscript truth:
reviewer risk:
durable corrections:

현재 상태는 첫 상태 체크리스트로 복원한다. 실험 protocol, reviewer risk, dataset convention도 여기에서 확인한다.

첫 AI 요청을 좁힌다

첫 요청은 templates/first-ai-session-prompt.md를 채워서 보낸다. 가장 작은 형태는 이렇다.

Read AGENTS.md and the first-day workspace checklist.
Before answering, state:
- object under truth control
- current evidence permits
- current evidence forbids
- smallest next action
- verification
Do not infer project truth from summaries when source files or artifacts are
available.

이 요청은 후보 설명이 연구 행동으로 바뀌기 전에 증거 상태를 확인한다. 첫 메시지는 artifacts/first-ai-session-message.txt처럼 파일로 남겨 두면 다음 세션에서 같은 읽기 순서를 다시 쓸 수 있다.

연구 루프를 하나만 고른다

처음에는 하나만 고른다.

상황 시작 템플릿
논문 한 편을 읽는다 paper-code-experiment-map.md
dataset 상태가 불명확하다 dataset-archaeology-sheet.md
실험 숫자를 해석한다 experiment-contract.md
에러를 좁힌다 stage-local-debugging.md
원고 문장을 고친다 claim-evidence-map.md

한 번에 여러 루프를 열면 요청 범위가 다시 넓어진다. 처음에는 작은 성공 하나가 좋다. 요청은 이렇게 좁힌다. "이 논문의 central claim, active code path 확인 대상, experiment protocol 빈칸을 분리하라."

결과를 기록에 남긴다

작업이 끝나면 project-memory.template.json이나 weekly-research-ledger.md에 세 줄을 남긴다.

현재 확인한 사실:
아직 말하면 안 되는 주장:
다음 행동:

AI가 틀린 assumption을 했다면 replay-case.md에 반복 확인 사례로 적는다. 같은 실수를 다음 세션에서 다시 설명하지 않기 위해서다.

첫 세션이 끝난 뒤 project-memory.json의 current_evidence, first_research_loop, claim_boundaries, next_smallest_actions를 함께 고친다. memory를 바꾸면 다음 AI 세션이 같은 근거 범위를 이어받는다.

부록 C — 예시 workspace

examples/first-robotics-workspace/는 quickstart를 따라 만든 작은 공개 예시다. 공개할 수 있는 파일 이름과 기록 단위만 남겼다. 새 사용자는 이 예시를 보고 자기 workspace에 맞게 이름과 경로를 바꾸어 쓴다. 연구 상태는 다음 세션에서 다시 읽을 수 있게 파일로 남긴다. 예시는 session, harness, sandbox 경계도 함께 보여준다.

파일 구조

examples/first-robotics-workspace/
├── AGENTS.md
├── README.md
├── project-memory.json
└── notes/
    ├── codex-porting-checklist.md
    ├── experiment-contract.md
    ├── first-ai-session-message.txt
    ├── first-ai-session-prompt.md
    ├── first-day-workspace-checklist.md
    ├── paper-code-experiment-map.md
    ├── stage-local-debugging.md
    └── weekly-research-ledger.md

이 예시가 보여주는 것

파일 역할
AGENTS.md AI가 먼저 읽는 project contract
README.md 예시 폴더만 열었을 때의 시작 순서
project-memory.json 현재 확인한 사실, 원 파일, 근거 범위, 연구 루프, 다음 행동
first-ai-session-message.txt AI 세션에 바로 넣는 메시지
codex-porting-checklist.md Claude/Cursor 중심 규칙을 Codex-first 규칙으로 옮기는 방식
first-ai-session-prompt.md AI 세션에 넣는 읽기 순서와 확인 기준
first-day-workspace-checklist.md 원 파일과 작은 행동 경계
paper-code-experiment-map.md 논문 읽기를 code path와 experiment protocol로 연결
experiment-contract.md 숫자를 주장으로 쓰기 전 필요한 protocol
stage-local-debugging.md ROS2 topic 문제를 stage-local check로 좁히는 방식
weekly-research-ledger.md 한 주의 주장, protocol, risk, next action

예시에서 배울 경계

이 예시는 AI가 어디서 시작해야 하는지 알 수 있을 만큼만 채운 상태다.

session record to update:
harness rule:
sandbox action:
current evidence permits:
current evidence forbids:
next smallest action:

이 여섯 줄이 있으면 AI는 같은 연구 상태에서 시작한다. 이 줄들이 없으면 AI는 일반적인 조언으로 돌아간다.

부록 D — 작업 흐름을 남기는 법

AI와 연구할 때 기록은 길 필요가 없다. 다음 세션이 같은 상태에서 시작할 만큼만 남기면 된다. 파일, 명령, 숫자, 원고 문장이 어디에서 왔는지를 남긴다.

다시 시작할 때 필요한 것

처음 말할 수 있는 범위는 작다.

workspace can be resumed
first research loop is selected
next small action is known

아직 말하면 안 되는 것도 적는다.

method works
experiment improved
reviewer risk is resolved

하나의 작업을 결과물로 남긴다

한 번에는 하나의 작업만 결과물로 남긴다. 논문 읽기라면 주장, code path, 실험 조건 표가 남아야 한다. 실험이라면 조건과 결과 출처가 남아야 한다. 디버깅이라면 stage별 명령 출력이 남아야 한다.

시작점 남길 것 확인할 항목
논문 한 편 paper-code-experiment-map.md 주장, code path, 실험 조건
dataset 확인 dataset-archaeology-sheet.md split, count, frame, convention
실험 숫자 experiment-contract.md, result-provenance-tuple.md 비교할 수 있는 조건
runtime 문제 stage-local-debugging.md tool/runtime/data/method failure 구분
원고 문장 claim-evidence-map.md 쓸 수 있는 문장과 보류할 문장

다음 AI가 같은 실험 숫자를 보고 아래 질문부터 묻는 상태가 좋다.

Which dataset?
Which split?
Which direction?
Which metric script?
Which baseline?
Which output?

반복 실패를 다음 작업 전에 잡는다

같은 correction을 두 번 이상 했다면 project memory, 주간 기록, 실험 조건 목록, 결과 출처 기록, 주장·근거 표, 반복 확인 사례 중 하나에 남긴다.

외부 agent repo도 이 기준으로 본다. coding discipline은 AGENTS.md로 옮기고, course repo는 학습 자료 구성만 참고하며, awesome list는 도구 발견에만 쓴다. 로보틱스 연구에는 dataset, metric, output, 주장, reviewer risk를 더한다.

매주 남길 세 줄

현재 확인한 사실:
아직 말하면 안 되는 주장:
다음 행동:

이 세 줄이 있으면 다음 세션은 바로 이어진다. 없으면 다음 세션은 다시 요약부터 시작한다.

멈출 때

AI가 계속 답을 만들 수 있어도 연구는 멈춰야 할 때가 있다.

중단 조건을 남기면 다음 행동이 작아진다.

부록 E — 출처

확인일: 2026-06-18

이 목록에는 공개 가이드에서 언급한 외부 repo와 이론 출처의 공개 링크를 모았다. 확인 범위는 링크 접근성, 제목·저자·repo 역할, 본문에서 인용한 최소 주장이다.

External Agent And Skills Repos

Human-AI Action Theory Sources

LLM Agent And Grounding Sources

Model Serving And Product-Layer Sources

Evaluation And Reproducibility Sources

Argument And Manuscript Sources

로컬 근거 자료, 대화 로그, 내부 작업 경로는 로컬 기록에 둔다.