gnet은 이렇게 움직여요 — 초등학생도 이해하는 설명서

이 문서는 gnet 이라는 프로그램이 안에서 어떻게 움직이는지 를 처음 보는 사람에게 설명해요. 어려운 말은 뒤로 미루고, 학교 모둠 과제(조별 과제) 에 빗대어 한 단계씩 풀어갈게요. 다 읽고 나면 친구한테도 설명해 줄 수 있을 거예요.

1. gnet이 뭐예요?

한 문장으로 말하면,

gnet은 내 컴퓨터에 있는 코드를 여러 AI 친구들이 모둠 과제처럼 함께 읽고 의견을 말해 주게 해 주는 도구예요.

조금 더 풀어서 이야기해 볼게요. 프로그램을 만드는 사람(프로그래머)은 수백, 수천 개의 파일 속에서 버그를 찾고 더 좋은 방법을 고민해야 해요. 혼자서 다 보기에는 양이 너무 많죠. 그래서 똑똑한 AI 친구(Claude)한테 도와 달라고 부탁하는데, 한 명한테 모두 맡기면 느리고 비싸요.

gnet은 이 문제를 이렇게 풀어요.

먼저 코드를 쓱 훑어보고 “어떤 친구들이 필요한지” 스스로 생각해요.
그다음 모둠장 한 명 + 여러 명의 모둠원 을 컴퓨터 화면 안에 불러요. (3명~16명까지)
모둠장이 일을 나눠 주면, 각 모둠원이 자기 일을 하고 공책 하나에 결과를 적어요.
다 끝나면 최종 보고서 한 장 으로 합쳐서 보여 줘요.

이 모든 게 내 컴퓨터 안에서만 일어나요. 인터넷 서버에 내 코드를 올리지 않아요.

2. 왜 이런 게 필요해요?

"AI 한 명한테 다 물어보면 되는 거 아냐?" 라고 생각할 수 있어요. 그런데 세 가지 문제가 있어요.

코드가 너무 많아요. 큰 프로젝트는 수천 개 파일이에요. 한 번에 다 읽을 수 없어요. 여럿이 나눠서 보는 게 훨씬 빠르고 꼼꼼해요.
전문이 달라요. 글씨체를 잘 보는 친구가 있고, 계산을 잘 보는 친구가 있듯, AI도 보안을 잘 보는 친구, 테스트를 잘 보는 친구 를 따로 두는 게 좋아요.
용돈이 아까워요. 똑똑한 AI 친구(오푸스, Opus)는 문제를 잘 풀지만 돈이 많이 들어요. 빠르고 싼 친구(소네트, Sonnet)도 섞어 쓰면 용돈을 반 가까이 아낄 수 있어요.

그래서 gnet은 “여러 AI 친구를 모둠처럼 묶어서 같이 일하게 하는 도구” 를 만든 거예요.

3. 모둠 과제 비유로 이해하기

학교에서 모둠 과제를 해 봤죠? gnet 안에서 일어나는 일을 교실에 있는 물건과 사람으로 바꿔 볼게요.

| gnet 안의 이름 | 모둠 과제에서는… | 하는 일 | |---|---|---| | 선생님 | 바로 여러분 (사용자) | 과제를 내주고, 다 된 걸 확인해요 | | 모둠장(오케스트레이터) | 제일 듬직한 친구 | 누구한테 뭘 맡길지 정해요 | | 모둠원(에이전트) | 각자 잘하는 친구들 | 맡은 부분을 깊이 봐요 (최대 16명) | | 모둠 공책(board.md) | 돌려가며 적는 노트 | 모두가 여기에만 글을 적어요 | | 선생님 일기장(events.jsonl) | 선생님이 쓰는 기록장 | 누가 언제 뭘 했는지 적혀요 | | 모둠 명단(roster.json) | 누구누구가 이 모둠인지 | 이름·역할·모델이 적혀요 | | 과제 안내문(analysis.md) | “오늘 할 과제는 이거예요” | 코드가 어떻게 생겼는지 요약해요 | | 발표문(final.md) | 모둠이 정리한 최종 글 | 선생님이 받는 결과물이에요 | | 교실 자리 배치(tmux) | 책상 네모나게 붙여 놓기 | 모둠원이 각자 앉을 화면이에요 |

글로만 보면 어려우니까, 그림으로도 볼게요.

┌──────────────── 교실 (tmux 세션) ────────────────┐
│                                                  │
│   [ 모둠장 자리 (Opus) ]                         │
│     └─ "너는 이거 봐 줘~" 하며 일을 나눠 줘요     │
│                                                  │
│   [친구1]  [친구2]  [친구3]  [친구4]  ...        │
│   (Opus)   (Sonnet) (Sonnet) (Opus)              │
│                                                  │
│        ↓ 다 같이 공책 하나를 돌려 봐요 ↓          │
│                                                  │
│   [모둠 공책: .gnet/board.md]                    │
│   [선생님 일기장: .gnet/events.jsonl]            │
└──────────────────────────────────────────────────┘

tmux 라는 건 “한 화면 안에 여러 개의 작은 화면을 네모나게 나눠서 같이 띄워 주는 프로그램” 이에요. 그냥 “교실 자리 배치 프로그램” 이라고 생각하면 돼요.

4. `gnet` 을 실행하면 무슨 일이 일어나요?

가장 중요한 부분이에요. 터미널에 gnet 이라고 치면, 컴퓨터 안에서 네 단계 가 순서대로 일어나요. 하나씩 볼게요.

1단계 — 코드 구경하기 (analyze)

gnet 을 켜면 제일 먼저, 프로젝트를 쓱 둘러봐요. 파일이 몇 개 있는지, 어떤 언어로 쓰였는지, 큰 파일은 어떤 건지 살펴보고, .gnet/analysis.md 라는 메모장에 정리해 두어요.

모둠 과제로 치면 “오늘 할 과제가 뭔지 먼저 읽어 보는 시간” 이에요.

일을 맡는 친구: lib/analyze.sh 라는 작은 스크립트
이 단계에서는 아직 AI 친구들을 안 불러요. 준비 단계예요.
결과물:
- .gnet/analysis.json (컴퓨터가 읽기 좋은 표)
- .gnet/analysis.md (사람이 읽기 좋은 글)

이때 .gnet/ 이라는 서랍이 프로젝트 안에 새로 생겨요. gnet이 일하는 동안 필요한 공책, 명단, 기록을 다 여기에 넣어 둬요.

2단계 — 모둠 짜기 (plan)

안내문이 준비됐으니 이제 어떤 모둠을 만들지 정해야 해요. 이걸 정해 주는 사람은 가장 똑똑한 AI 친구(오푸스, Opus)예요. 이 친구한테

“이 프로젝트를 보려면 어떤 전문가들이 필요해?”

라고 물어봐요. 그러면 오푸스가 모둠 명단(roster.json) 을 써 줘요. 이 명단에는 이런 정보가 들어 있어요.

친구의 이름 (예: security_auditor, test_reviewer)
뭘 잘하는지 (역할)
어떤 AI를 쓸지 (오푸스 or 소네트)
어떤 파일을 읽어야 하는지
모둠장이 처음에 시킬 일
일을 맡는 친구: lib/plan.sh
결과물: .gnet/roster.json

참고: Opus가 모둠을 짜는 이 부분을 “메타 플래너(meta-planner)” 라고 불러요. 어렵게 들리지만, 그냥 “계획 짜 주는 사람” 이라는 뜻이에요.

3단계 — 자리 앉기 (spawn)

명단이 나왔으니 이제 친구들이 교실에 와서 앉아야 해요. 이 일을 하는 프로그램이 자리를 펴고(tmux 패널을 만들고), 친구들을 순서대로 앉혀요.

맨 위 자리 → 모둠장(오케스트레이터) 이 앉아요. 항상 오푸스예요.
나머지 자리 → 모둠원 이 한 명씩 앉아요.

친구들은 자리에 앉자마자 자기 역할이 뭔지(시스템 프롬프트), 모둠 공책은 어디에 있는지를 안내받아요. 그리고 “네가 맡을 첫 번째 일은 이거야” 라는 쪽지도 받아요.

일을 맡는 친구: lib/spawn.sh, lib/launch_orchestrator.sh, lib/launch_agent.sh
결과물: 컴퓨터 화면에 진짜로 여러 개의 Claude 창 이 쫙 펼쳐져요.

이 단계가 끝나면 선생님(여러분)은 tmux 교실에 딱 들어가서 모둠이 일하는 모습을 바로 옆에서 볼 수 있어요.

4단계 — 모둠 과제 하기 (진짜 일하는 단계)

이제 본 게임이에요. 모둠장이 공책에 “오늘 할 일” 을 적고, 친구들한테 한 명씩

“너는 로그인 부분 봐 줘.” “너는 테스트 잘 돌아가는지 봐 줘.”

이렇게 일을 나눠 줘요. 이 “쪽지 보내기”를 하는 명령이 gnet-ask 예요.

친구들은 맡은 일을 하고, 결과를 항상 같은 공책(board.md) 에 적어요. 다른 친구가 뭘 썼는지도 공책을 보면 알 수 있어요. 그래서 서로 겹치지 않고, 서로의 발견을 이어서 일할 수 있어요.

그동안 선생님 일기장(events.jsonl)에는 누가 언제 무엇을 했는지 가 자동으로 기록돼요. 나중에 “어떻게 된 일이었지?” 하고 궁금할 때 이 일기장을 보면 알 수 있어요.

모둠장이 쓰는 명령: gnet ask <친구 이름> "해 줄 일"
친구들이 글 쓰는 공책: .gnet/board.md
자동 일기장: .gnet/events.jsonl

여러분은 중간에 어떤 친구의 자리에 들어가서 직접 말을 걸 수도 있어요. tmux에서 한 칸을 크게 키우고 질문을 적으면, 그 친구가 바로 답해 줘요. 진짜 모둠 과제처럼요.

5. 친구들은 누구일까요? (모델 이야기)

모둠 안에는 두 종류의 친구가 있어요. gnet은 이 둘만 써요.

| 이름 | 진짜 이름 | 특징 | 맡기는 일 | |---|---|---|---| | 오푸스 (Opus) | claude-opus-4-7 | 똑똑해요. 오래 고민해도 길을 잘 찾아요. 용돈이 많이 들어요. | 모둠장, 그리고 어려운 주제 (보안, 설계, 성능, 데이터) | | 소네트 (Sonnet) | claude-sonnet-4-6 | 빠르고 가벼워요. 용돈이 적게 들어요. | 테스트 보기, 문서 확인, 스타일 점검, 프런트엔드 살피기 |

“그럼 제일 어린 하이쿠(Haiku) 도 있지 않나요?” 하고 물어볼 수 있어요. gnet은 일부러 하이쿠를 안 써요. 너무 간단해서 “코드를 깊이 읽고 의견 내기” 에는 어울리지 않거든요. 모둠 명단을 짤 때 하이쿠가 끼어 있으면 바로 거절돼요.

왜 둘을 섞어서 써요?

간단해요. 용돈을 아끼려고요. 어려운 일은 오푸스, 쉬운 일은 소네트한테 맡기면 전체 비용이 절반 가까이 줄어요. gnet은 일이 끝난 뒤에 gnet savings 명령으로 “이번에 얼마나 아꼈어요” 를 정확한 숫자로 보여 줘요.

6. 끝나면 뭐가 나와요?

모둠 과제가 끝나면 선생님한테 발표문 한 장 을 내야겠죠. gnet도 똑같아요. 세 가지 마무리 명령이 있어요.

`gnet synth` — 발표문 만들기

친구들이 공책에 쓴 내용을 전부 모아서 한 편의 글(final.md) 로 합쳐 줘요. 이 작업도 오푸스가 맡아요. 합친 글은 .gnet/final.md 에 저장되고 화면에 바로 보여요.

`gnet savings` — 얼마 아꼈는지 보기

“오푸스 혼자서 다 했을 때와 비교하면 얼마나 싸게 끝났어요?” 를 계산해 줘요. 보통 40%~60% 정도 싸게 나와요.

`gnet resume` — 다음 날 이어서 하기

오늘 모둠 과제를 끝까지 못 하고 집에 가야 할 때가 있죠? 그럴 때 내일 gnet resume 이라고 치면, 똑같은 친구들이 똑같은 공책을 펴고 이어서 할 수 있어요. 명단(roster.json)과 공책(board.md)이 그대로 남아 있어서 가능한 거예요.

그 밖의 명령들

gnet attach — 이미 켜진 교실에 다시 들어가기
gnet status — 지금 모둠에 누가 있는지, 교실이 켜져 있는지 보기
gnet kill — 교실을 정리하고 문을 닫기 (세션 끝내기)
gnet --fresh — .gnet/ 서랍을 통째로 버리고 아예 처음부터 새로
gnet gui — 웹 브라우저에서 예쁜 화면(대시보드)으로 모둠 상태 보기
gnet voice — 마이크에 말하면 글자로 바꿔서 친구한테 전달해 주기

7. 어려운 단어 사전

본문에서 괄호로 살짝 나왔던 단어들을 한 줄씩 풀어 놓을게요.

CLI: “커맨드 라인 인터페이스”. 마우스 클릭 대신 글자로 명령을 내리는 방법 이에요. gnet은 CLI예요.
tmux: 한 화면을 네모나게 쪼개서 여러 개의 터미널을 동시에 띄우는 프로그램. gnet의 “교실 자리 배치”를 맡고 있어요.
패널(pane): tmux 화면 한 칸. 친구 한 명이 앉는 책상 하나 예요.
세션(session): 지금 켜져 있는 교실 전체. gnet kill 로 닫을 수 있어요.
에이전트(agent): AI 친구 한 명. 모둠장 포함해서 최대 16명까지 있어요.
오케스트레이터(orchestrator): 모둠장. 일을 나눠 주는 사람이에요.
Opus / Sonnet: 두 가지 AI 친구. 똑똑이(오푸스)와 빠름이(소네트).
Haiku: 또 다른 종류의 AI지만 gnet에서는 안 써요.
roster.json: 모둠 명단 이 담긴 파일. JSON이라는 컴퓨터 글씨로 쓰여 있어요.
board.md: 모둠 공책. 모두가 여기에만 글을 적어요.
events.jsonl: 선생님 일기장. 누가 언제 뭘 했는지 한 줄씩 적혀요.
analysis.md: 과제 안내문. 코드가 어떻게 생겼는지 요약한 글이에요.
final.md: 최종 발표문. gnet synth 를 하면 만들어져요.
MCP: “다른 프로그램이 gnet의 공책·명단을 읽거나 쓸 수 있게 해 주는 전화기” 정도로 생각하면 돼요. gnet mcp 로 켜요.
프롬프트(prompt): AI 친구한테 건네는 지시문/인사말. 각 친구는 자기 역할에 맞는 프롬프트를 받고 시작해요.

한 줄 요약

gnet은 내 코드를 훑어보고, 똑똑한 모둠을 짜고, 교실처럼 자리 배치한 뒤, 모둠 공책에 결과를 적어가며 함께 일해서, 최종 발표문 한 장을 만들어 주는 도구예요.

궁금한 게 있으면 README.md → docs/PITCH.md → 이 문서 순서로 읽어 보세요. 먼 옛날 지휘자와 오케스트라로 불리던 것을, 이 문서에서는 모둠장과 모둠원으로 바꿔서 설명했을 뿐 안에서 일어나는 일은 똑같아요.