발행 순서와 읽는 순서는 다르다 — 30편 지도와 15주제 교차 참조

agentic-coding 카테고리에는 이 글을 뺀 30편이 있다. 한 편씩은 각자 완결돼 있다. 문제는 30편을 앞에서부터 통째로 읽으라고 하면 대부분 중간에서 멈춘다는 것이다 — 지금 필요한 것이 어디 있는지 모르는 채로 읽기 때문이다.

이 글은 그 30편의 지도다. 같은 30편을 두 번 갠다.

• 시리즈 축 — 발행 구조 그대로다. 8개 시리즈와 어디에도 속하지 않는 2편. 순서대로 읽을 때 쓴다.
• 주제 축 — 15개 주제 각각을 깊이 순서로 늘어놓는다. 열다섯 중 열넷만 가장 깊은 자리가 차 있다. 아는 주제를 찾아갈 때 쓴다.

두 축이 어긋난다는 것이 지도가 필요한 이유다. 시리즈의 첫 편이 어떤 주제에서는 3차로 내려가는 자리가 다섯이다 — claude-md-context의 첫 편은 주제 7(컨텍스트·토큰 예산)에서 3차다. 그리고 어느 시리즈에도 속하지 않는 독립편 하나가 주제 15(조직 도입과 측정)의 1차다.

30편이 어떻게 묶여 있는가

여덟 시리즈가 28편이고 독립편이 2편이다. 묶음 이름 넷(기반·설계·운영·답부터)은 이 글이 붙인 것이지 각 시리즈가 스스로 선언한 상위 분류가 아니다.

시리즈별 30편

기반 — claude-code-tools 4편

기반 — claude-code-extensions 3편

기반 — claude-md-context 3편

설계 — subagent-design 3편

설계 — agent-definition-catalog 3편

운영 — rules-hooks-skills 4편

운영 — agent-operations 4편

답부터 — agentic-coding-qna 4편

독립편 2편

여기까지가 30편 전부다 — 4 + 3 + 3 + 3 + 3 + 4 + 4 + 4 + 2로 합이 30이다. 각 칸의 한 줄 설명은 그 편이 무엇을 다루는지 가리키기만 한다. 표와 수치는 전부 해당 편 안에 있다.

목적별 읽는 순서

시간이 없으면 전부 읽지 않는다. 목적을 하나 고르고 네다섯 편에서 멈추는 편이 낫다.

여덟 경로의 순서는 이 글이 짠 것이다. 각 편이 스스로 선언한 선행 관계가 아니라, 30편을 놓고 「무엇을 먼저 알아야 다음이 읽히는가」로 배열한 결과다.

여덟 경로의 자리를 다 세면 34개다. 그중 네 편이 두 경로에 겹쳐 나오므로 중복을 걷어내면 30편 전부가 된다. 두 번 나오는 넷은 내장 도구 편·settings.json 편·3계층 통제 편·enforcement 편이고, 앞의 셋은 「거버넌스와 보안을 본다」 경로에서 한 번 더 불린다.

주제에서 글로 — 15주제 교차 참조

같은 주제가 여러 편에 흩어져 있다. 주제를 알고 들어오는 경우에는 이쪽이 빠르다.

주제 열다섯 중 열하나와 1차·2차·3차라는 깊이 3단은 원 자료의 교차 참조표에서 받았다. 나머지 주제 넷을 세우고 서른 편을 각 자리에 배정한 것이 이 글의 판정이다. 각 편이 그 주제를 글의 주어로 삼는가(1차) · 한 절로 다루는가(2차) · 곁가지로 언급하는가(3차)로 갈랐다. 분량은 보조 근거로만 썼다. 다른 기준으로 재면 순서가 달라질 수 있다.

「함께 볼 것」 열은 깊이 순서 밖이다. 같은 주제를 다른 각도에서 건드리는 편을 적었다.

이 표를 세어 보면

쉰네 자리에 서른 편이 들어간다. 어느 편도 이 표에서 빠지지 않는다 — 단 깊이 순서만 세면 스물일곱 편이고, 나머지 세 편은 깊이 순서 밖인 「함께 볼 것」 열에만 있다.

1차 자리가 열넷인 것은 주제 10에 1차가 없기 때문이다. 그리고 그 열넷을 채우는 편은 열셋이다 — 라우팅 붕괴 편이 비용 통제와 확장·스케일링 두 주제의 1차를 겸한다. 나머지 열일곱 편은 1차를 한 번도 받지 못했다. 그중 열넷은 2차나 3차로 들어가고, 어떤 편은 여러 주제에서 여러 번 불린다. 남는 세 편 — 확장 메커니즘 Q&A · 운영과 거버넌스 Q&A · JD 5필드와 트리거 셋 — 은 1차도 2차도 3차도 아니고 「함께 볼 것」으로만 불린다.

주제 10에 1차가 없는 것에 대해

사람이 승인하는 지점을 글의 주어로 삼는 편이 이 카테고리에 없다. 열다섯 주제 중 1차가 비어 있는 유일한 자리다.

2차·3차로 세운 두 편과 「함께 볼 것」에 적은 두 편이 그 자리를 나눠 메운다. 30개 에이전트 카탈로그 편은 사람 검수 필요도로 서른 종을 세어 본 절을 따로 두고, 에이전트 설계 Q&A 편은 사람 손이 마지막으로 닿는 자리를 어디에 둘 것인가를 문항 제목 둘로 받는다. 정의서 공통 스키마 편은 서른 개의 정의서 중 승인 게이트를 갖춘 것이 몇 개인지를 다른 항목들과 나란히 세고, 운영과 거버넌스 Q&A 편은 그 게이트를 사전·사후 두 시점으로 가른다.

이 글의 판단은 그 빈칸을 채우지 않고 그대로 두는 것이다. 2차를 1차로 올려 적으면 없는 깊이를 있다고 말하는 것이 되고, 그 편을 찾아간 독자가 기대한 것을 찾지 못한다. 빈칸이 보이는 편이 낫다.

결론부터 보려면 — Q&A 4편

네 편은 나머지 26편을 다시 자르지 않는다. 같은 내용을 질문 형태로 먼저 만나게 한다. 어떤 시리즈로 들어갈지 정하지 못했을 때 진입점으로 쓴다. 어느 편이 무엇을 받는지는 위 시리즈 표의 「답부터」 묶음에 이미 적었으므로 여기서 다시 펼치지 않는다.

문항 수는 각 편 제목에 그대로 적혀 있는 값이고(17·12·10·17), 넷을 더하면 쉰여섯이다. 네 편 모두 본문에서 이 카테고리의 다른 편으로 링크를 걸어 두었으므로, 답이 짧게 느껴지는 문항은 그 링크를 따라 내려가면 된다.

닫으며

지도는 두 번 쓰인다. 들어올 때 어디부터 볼지 정하는 데 한 번, 이미 읽은 뒤에 「그게 어디 있었더라」를 찾는 데 한 번.

앞쪽 용도라면 목적별 경로에서 하나를 골라 네다섯 편을 읽고 멈추는 것이 30편을 순서대로 훑는 것보다 낫다. 뒤쪽 용도라면 주제 교차 참조 표에서 주제를 찾아 1차부터 내려가면 된다. 두 축이 어긋나는 자리 — 시리즈 첫 편이 어떤 주제에서는 3차인 자리 — 가 있어서 한쪽만으로는 찾아지지 않는 편이 생긴다.

남겨 둘 것 하나는 열 번째 주제다. 사람이 승인하는 지점은 1차가 비어 있는 유일한 주제이고, 그것을 지도에 빈칸으로 적어 두는 편이 아무 편이나 끌어다 채우는 것보다 정확하다고 봤다.