2026-11-09 LLM · 에이전트를 위한 안내서 시안, 아키텍처의 도구 절 옮기기
0.2.0을 낸 지 닷새 뒤의 세션이다(11-09에 시작해 11-10로 넘어감). 시작할 때 inbox에 새 항목이 둘 있었다. 이 기록은 매듭(11-10)에서 썼다. 그때 에이전트 셋이 돌고 있었다: LLM 안내서 구현, AT-05 점검 모드(worktree), 함께 바뀔 곳의 조사. 그 결과는 이 기록에 들지 않는다.
문서와 저장소의 도구 절을 옮김
메인테이너는 아키텍처 문서의 8.3절이 “거기에 있을 내용이 아닙니다”라고 했다. 제품이 아니라 저장소에서 일하는 도구라서 3. 문서로 옮겼다(메인테이너가 추천안을 고름). 데스크톱 프레임워크의 미결정은 9.1 제품에 들어가는 것으로 옮겼다. 커밋 6144a7f(에이전트)
LLM · 에이전트를 위한 안내서
메인테이너가 “먼저 시안으로”를 골랐다. 시안은 M56(https://claude.ai/artifact/RruS69wvMC5iyCkoWW6Erm, journal/assets/2026-11-09-llm-guide-study.html)이다. 저장소를 모르는 새 에이전트(haiku · sonnet · opus)에게 안내서 초안만 주고 그림을 그리게 해서, 실제 parseModel로 검사했다. 23번에 21번 통과했고, 실패 둘은 haiku가 링크를 손으로 인코딩하다 괄호 하나를 틀린 것이다.
-
시안을 만드는 중에 메인테이너가 덧붙였다: “다른 에이전트에게 안내할 때, “공유 링크 복사” 기능을 추천해주세요.” 안내서 v2부터 이것을 기준으로 삼았다.
-
메인테이너가
u·d·j의 뜻을 물었다. 시안에 꾸림을 설명하는 표가 없어서 더했다. -
메인테이너가 ChatGPT에게 같은 요청을 해 본 답을 알려 주었다: “요청하신 AriadneNSD는 현재 페이지가 로딩 화면으로만 확인되어 제가 직접 다이어그램을 입력하거나 저장하지는 못했습니다.” ChatGPT는 첫 화면 HTML만 읽었고 앱을 조작하려 했다. 그래서 LG1에 4번(첫 화면 HTML 안에 짧은 안내를 바로 둠)을 더해 추천으로 바꿨다.
-
메인테이너: “모두 추천을 수용합니다.” 정한 것: LG1 4번(영어
/llms.txt+ 첫 화면 안의 짧은 안내), LG2u꾸림을 앱이 읽기만, LG3/model.schema.json, LG4 R-WEB-10P1, LG5 공유 링크 복사는d그대로, LG6 열지 못한 링크의 까닭을 보이고 복사하게. 구현은 에이전트에게 맡김 -
시안 에이전트가 라이선스 꼬리말 스크립트(
2026-10-14-add-license-note.py)를 돌리자 꼬리말이 없던 다른 시안 21개(10-22 ~ 11-03)에도 넣었다. 에이전트가 넣은 줄만 지워 되돌렸다. 그 21개에 꼬리말이 없는 것은 따로 볼 일이라 backlog에 둠 -
시안 페이지는 만드는 스크립트(
…-build.mjs)가 있지만, 꾸림의 표와 LG1의 사례 · 4번은 Claude가 HTML에 바로 더했다. 스크립트로 다시 만들면 사라진다
구현을 맡긴 에이전트에게 정합성 검사 둘(예제를 테스트로, 값 목록을 코드에서)도 더했다(아래).
MVP의 인수 기준
메인테이너: “현재 버전이 MVP 인수조건을 만족하나요?” 인수 테스트 17개 가운데 13개는 자동으로 끝났고, AT-05 · AT-08 · AT-10 · AT-14는 Chromium 부분만 자동이다. 사람이 볼 몫(기준 기기의 성능, 다른 뷰어, Firefox · Safari)이 남아 “모두 지났다”고는 말할 수 없다 → 5.2 MVP의 인수 기준, MVP 개발
AT-05를 어떻게 하느냐는 물음에 Claude가 기준 기기를 고르라고 물었다. 메인테이너가 창을 거절하고 다시 물었다: “내 질문은 1. 500개 블록을 손으로 만드나? 무언가 도구가 있을 것 같다 2. 측정은 어떻게 하나? 시계와 눈으로 하나? 입니다.” 블록은 테스트 코드의 largeDocument(500)이 만들고, 시간은 performance.now()로 잰다고 답했다. 개발 환경 없이 다른 기기에서 재도록 점검 모드(?perf)를 제안했고, 메인테이너: “네, 점검 모드를 만들어 주세요.” 에이전트가 worktree에서 만드는 중. 기준 기기는 그 뒤에 정한다.
outbox에서 받은 답
- 새 ADR 넷: 메인테이너가 넷 모두 승인. 0042 · 0044 · 0045는 승인으로 바꿈(
484ed39). 0043은u꾸림을 더한 뒤 승인으로 바꾼다 - 첫 내려받기 한도 230 KB: “230 KB 그대로”
- 세션 06에 정한 것 7묶음: 메인테이너: “다음 세션에서 결정하겠습니다."
"레인”이라는 말
메인테이너: “밤사이 레인이 뭔가요? 레인? lane인가요?” 11-03 밤에 에이전트 다섯이 나눠 만든 묶음을 Claude가 “레인 1” ~ “레인 5”라고 불렀는데, 설명 없이 outbox와 UX 결정 모음의 절 이름에 썼다. 메인테이너가 바꾸자고 해서, 에이전트가 고치는 파일과 겹치지 않게 그 에이전트가 끝난 뒤 바꾼다 → backlog
정합성 지키기
메인테이너: “작업이 커져서 앞으로 문서나 /llms.txt의 정합성이 안 맞을 것이 걱정됩니다. 이런 문제를 어떻게 미연에 방지할 수 있을까요? 정합성을 유의해야할 부분을 식별해둔다든지 무언가 다른 엔지니어들이 쓰는 방법이 있을 것 같군요.” Claude가 넷을 보였고 메인테이너가 모두 골랐다: 원본에서 뽑기, 예제를 테스트로, 함께 바뀌는 곳의 짝과 검사, 출시 전 LLM 시험.
- 앞의 둘은 LLM 안내서 에이전트에게 더함. 짝의 표는 조사 에이전트가 코드와 문서를 훑는 중. 출시 전 LLM 시험은 02-test-architecture의 출시 전 점검에 더할 것
- 메인테이너: “정합성을 위한 방법들도 문서에 기록해주세요.” 원본은 13. 문서와 코드의 정합성, 흐름은 9. 정합성 지키기(
a0afaf8)
발견한 위험
- 에이전트 둘(LLM 안내서는 main, 점검 모드는 worktree)이
06-web·07-testing등 같은 문서를 고칠 수 있어, 합칠 때 충돌이 날 수 있다 - 시안 M56의 HTML은 만드는 스크립트와 어긋나 있다(위)
다음 할 것
- 에이전트 셋의 결과를 받아 합치고, 전체 테스트를 돌리고, 로컬로 보여 드림. 그 뒤 ADR-0043 승인, “레인” 이름 바꾸기, 출시 전 LLM 시험을 07-testing에
- 배포한 뒤 메인테이너가 ChatGPT · Grok에게 같은 요청을 다시 해 봄
- 다음 세션: outbox의 세션 06 7묶음
매듭 뒤 (2026-11-10)
합치기
- 함께 바뀌는 곳의 조사 보고 →
journal/assets/2026-11-10-co-change-survey.txt. 메인테이너: “함께 고치게 하세요” - 점검 모드가 끝남. AT-05가 CPU 4배 감속에서 8가지 명령 모두 불합격(p95 280 ~ 750ms, 감속 없이는 58 ~ 77ms) → MVP 개발
- LLM 안내서가 끝남(LG1 ~ LG6, 예제를 테스트로, 값 목록을 코드에서). 실험의
u링크 20개 가운데 18개가 실제 앱에서 열림 - 합치는 에이전트가 점검 모드를 합치고(테스트 ID T-1147 ~ T-1160으로 다시 매김), ADR-0043을 승인으로, “레인”을 풀어 씀. 시간 단언은 커버리지 기록 중에 건너뜀(T-0487 · T-1126)
- 메인테이너: “모델 JSON의 JSON Schema도 설계의 중요한 부분입니다. 문서에 포함시켜 다른 사람들이 볼 수 있게 하는 것이 좋을 것 같습니다.” → 스키마에서 만드는 02-model-schema
- 정합성 에이전트: 규칙 C1 ~ C10(
src/scripts/co-change.json), 값을 견주는 테스트 11개(빠진 단축키 둘, 문서에만 있던 색, 개발 도구 여섯 등을 맞춤), 스키마 문서, 출시 전 LLM 시험. 커밋 훅은 메인테이너가 “넣기”를 골라 켬(edbdb7c) - 메인테이너: ""까닭 복사”라는 말이 어색합니다.” → “오류 내용 복사”. 영어는 “영어 문구는 “Copy Reason” 그대로 좋습니다.”
오래 걸린 까닭
메인테이너: “오늘 작업이 너무 오래 걸렸는데 어느 부분에서 오래 걸렸나요?” 차례로 이은 에이전트 일만 2시간 반(시안 20분 → 구현 54분 → 합치기 44분 → 정합성 31분). 까닭: 에이전트마다 전체 검사를 되풀이함, 나란히 돌아 시간 테스트가 흔들려 다시 돎, 같은 파일 때문에 기다림, 테스트 ID가 겹침. 규칙을 CLAUDE.md와 2. 세션의 리듬에 적음(5176da2): 에이전트는 바뀐 곳만 검사하고 전체 검사는 합칠 때 한 번, 번호 · 포트 범위는 미리 나눔, 시간 테스트는 혼자 돌 때만 믿음
AI 넷의 시험
메인테이너: “ChatGPT로 얼른 테스트를 해보고 싶군요” → 검사를 마친 d2fc3a4까지만 push해 배포. 넷의 결과(기록은 journal/assets/2026-11-10-*):
| AI | 한 일 | 결과 |
|---|---|---|
| ChatGPT (하노이탑) | HTML을 읽고 안내서를 따름 | 첫 링크는 호출 블록에 text를 넣어 깨짐. “까닭 복사”한 글을 받고 스스로 고쳐 열림. 안내서에 “호출 블록에는 text가 없다”를 더함(2bbb351) |
| Grok | 화면을 띄워 조작하려 함 | 링크 없음. 첫 화면 안내가 앱이 뜨면 사라져서. #root 밖의 보이지 않는 글과 도움말 › “AI에게 그려 달라고 하기”를 더함(LG7, eaa768d · 989afd7) |
| Gemini | 안내서대로 u 링크 | 안 열림: Gemini 앱이 링크를 Google 검색으로 감쌌고, 손 인코딩에서 마지막 블록이 망가짐. 코드 블록의 JSON은 맞음 |
| claude.ai | 브라우저 조작을 하려 함 | 연결이 없어 멈춤. 페이지를 읽지 않음 |
알게 된 것: LLM의 JSON은 거의 늘 맞고, 틀리는 것은 링크로 바꾸는 단계와 채팅 앱이 링크를 바꾸는 일이다. 페이지를 열지 않는 AI에게는 사용자의 요청문에 /llms.txt 주소를 넣어야 한다.
Claude가 JSON 붙여넣어 열기 · 요청문 복사 · 안내서 손질을 제안했다. 메인테이너: “잠시만요. https://claude.ai 의 결과까지 보고 작업하시지요”. 그 뒤 고르는 창을 두 번 닫고 말을 짚었다: “안내문은 llms.txt를 말하나요?”(Claude가 “안내서” · “첫 화면의 안내” · “요청문”을 섞어 써서 표로 나눠 답함), “기존에는 슈도코드를 붙여넣어 다이어그램을 그렸지요? JSON 붙여넣어 열기 기능을 추가하면 그 기능과 충돌할까요?”(의사코드 변환 R-CODE-01은 아직 없고, 지금은 글을 붙이면 줄마다 처리 블록이 되어 그대로면 충돌한다. 알아보는 기준을 좁게 하고 물으면 피한다). 메인테이너: “네, 시안으로 보여 주세요. 그러나 다음 세션에서 읽어보겠습니다.” → 시안 M57
다음 할 것
- 다음 세션 처음: M57을 보고 JP · RQ · GD를 정함 → 정해 주세요
- AT-05의 프로파일링, outbox의 세션 06 7묶음과 2026-11-10 에이전트가 정한 것
inbox
처리한 항목의 원문(1. 일하는 방식):
[[01-architecture#83-문서와-저장소의-도구|8.3 문서와 저장소의 도구]]는 거기에 있을 내용이 아닙니다.
(원문의 링크는 절을 옮겨 가리킬 곳이 없어졌으므로 코드 표기로 남긴다. 그 내용은 지금 3. 문서에 있다.)
처리한 항목의 원문(5. 질문/요청):
- 예를들어 Grok이나 ChatGPT같은 다른 LLM에게 또는 다른 claude에게 “https://ariadnensd.com 으로 버블소트 알고리즘을 nsd로 그려주세요”라고 했을 때, 그 LLM들에게 도움이 되려면 무엇을 준비해야될까요? LLM과 에이전트를 위한 안내서를 웹 버전에 포함시킬 수 있나요?