0. 이 안내서를 읽는 법

이 안내서는 fig-atlas로 논문 그림을 만들고 관리하는 연구자를 위한 글입니다. 프로그래밍이나 AI를 잘 몰라도 읽을 수 있게 썼습니다. 도구 안에서 무엇이 어떻게 돌아가는지보다 내가 무엇을 하고, 무엇을 확인하면 되는지를 다룹니다.

두 가지 사용 방식

같은 일을 두 가지 방법으로 할 수 있습니다. 이 안내서는 첫째를 중심으로 쓰고, 둘째는 각 장에 한 줄씩 붙입니다.

방식	이렇게 합니다	이런 분께
💬 AI에게 말로 시키기	AI 도우미(Claude Code, Gemini CLI, Antigravity, opencode 등)에게 "이 데이터로 그림을 만들어 줘"라고 말합니다. AI가 fig-atlas의 명령을 대신 실행하고, 파일을 바꾸기 전에 무엇이 바뀌는지 보여 줍니다.	대부분의 연구자
⌨ 명령	터미널(명령 창)에 fa build 프로젝트이름처럼 직접 입력합니다.	직접 실행하고 싶을 때. 명령 목록은 부록 C

특정 편집기나 프로그램이 필요하지 않습니다. 설정 파일은 어떤 글 편집기로든 열고 고칠 수 있고(메모장, VS Code 등), 결과 그림은 파일 탐색기에서 엽니다. 몇몇 장에는 💡 팁으로 특정 편집기(예: VS Code)를 쓸 때 편한 방법을 덧붙였지만, 몰라도 됩니다.

AI 도우미를 처음 연결하는 방법은 AI 에이전트 연결에 있습니다. 연결은 한 번만 하면 됩니다.

먼저 알아 둘 단어 다섯 개

단어	뜻	실험에 빗대면
번들 (bundle)	그림 한 칸(패널)에 들어갈 데이터 묶음. 표 파일 하나와 "무슨 그림인지" 적은 메모 파일 하나로 된 폴더입니다.	라벨 붙은 시료
프로젝트	그림 한 장(여러 패널)을 만드는 단위. 설정 파일, 분석 파일, 그림 설명 파일 세 개로 이루어집니다.	실험 하나
config (설정 파일)	그림의 색·크기·축 범위·배치가 모두 적힌 글 파일. 연구자가 그림을 고치는 곳입니다.	프로토콜
빌드 (build)	설정대로 그림을 다시 그리고, 검사하고, 기록을 남기는 한 번의 실행.	실험 실행
출처 기록 (provenance)	그림이 어떤 데이터·설정·프로그램으로 만들어졌는지 자동으로 남는 기록.	실험 노트

나머지 용어는 부록 A(용어집)에 모아 둡니다.

읽는 순서

• 처음이라면 1장(왜 필요한가)과 2장(한눈에 보기)을 먼저 읽고, 4장을 따라 그림을 하나 만들어 보세요. 직접 해 보는 연습은 튜토리얼: 첫 그림에도 있습니다.
• 그림을 고치려면 6장(config 읽고 쓰기)을 보세요.
• 필요할 때 찾아 읽어도 됩니다. 각 장은 따로 읽어도 이해되게 썼습니다.

이 안내서 전체에서 하나의 예를 따라갑니다. 용량-반응 실험 그림이 논문 Figure가 되기까지입니다. 예제 데이터는 저장소의 examples/ 폴더에 들어 있어서 누구나 똑같이 해 볼 수 있습니다.

---

다음: 1. 왜 이런 도구가 필요한가