Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
AI에게 단순한 문서 작성을 요청했지만, Claude는 소스 코드와 레포지토리 구조를 분석하여 Linux 환경에서 실제 구동 테스트까지 완료하고 그 결과를 문서에 포함시켰습니다. 이는 AI 에이전트가 소프트웨어의 최초 이용자 역할을 할 수 있다는 가능성을 제시합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기「이 리포지토리를 읽고, 일본어 문서를 만들어 주세요」
Claude에게 부탁한 것은 그뿐이었다.
그런데 돌아온 문서에는 코드에서 읽어낸 구조나 구동 절차뿐만 아니라, Linux 환경에서 Glypha를 실제로 구동한 결과까지 적혀 있었다. 테스트를 통과시키고, 렌더러를 빌드하고, 콘텐츠를 업로드하여 일본어가 표시되는 곳까지 확인되어 있었다.
문서를 작성해 달라고 했을 뿐인데, AI가 먼저 소프트웨어를 사용하기 시작했다.
이 글에서는 그때 무슨 일이 일어났는지, 생성된 문서에서 확인할 수 있는 사실에 초점을 맞춰 되돌아본다. 그리고 거기서 파생된 'AI 에이전트는 소프트웨어의 최초 이용자가 될 수 있을까'라는 질문에 대해 생각해 보고자 한다.
Glypha는 Go와 TypeScript/PixiJS로 만든 실험적인 디지털 사이니지이다.
콘텐츠는 화면에 표시할 문자나 이미지, 시간별 전환을 정의한 JSON으로 만듭니다. 이를 HTTP API로 보내면, 서버가 내용을 검증하고 브라우저의 렌더러가 표시합니다.
Glypha에서는 AI 에이전트가 콘텐츠를 생성하거나 업데이트하는 것도 상정하고 있습니다. 다만, AI에게 세부적인 조작 절차를 강제하는 설계는 아닙니다. 대신 시스템 측에서 입력을 엄격하게 검증합니다.
예를 들어, 문자가 지정된 직사각형을 벗어난다거나, 존재하지 않는 이미지를 참조하거나, 폰트에 없는 문자를 사용하는 등의 콘텐츠는 이유와 함께 거부됩니다. 실패한 입력이 지금까지 정상적으로 표시되던 화면을 덮어쓰지도 않습니다.
저는 이 사고방식을 '자유롭게 하도록 하는 제약'이라고 생각합니다. 자세한 설계 이야기는 지난 글에 넘기겠지만, 이번 실험은 뜻밖에 그 사고방식을 문서 작성 측면에서 시험하게 되었습니다.
Glypha에서는 AI를 통한 문서 생성도 시도해 보고 싶었기에, 개발 당시의 문서를 의도적으로 영어로 준비했습니다. 그래서 Claude에게 GitHub 리포지토리 URL을 전달하고 다음과 같이 요청했습니다.
어제 만든 것이지만, 이 코드와 레포지토리 AI 실험도 겸해서
일부러 일본인이 읽기 어렵게 영어로 만들고 있습니다.
...
이 프롬프트에는 Linux에서 구동하도록 지정하지 않았습니다. 테스트를 실행하거나 샘플 콘텐츠를 업로드하라고 부탁하지도 않았습니다.
기대했던 것은 영어 README나 설계 문서, 소스 코드를 바탕으로 한 일본어 해설이었습니다.
완성된 'Glypha 설명 문서'는 개요, 내부 구조, Docker 및 호스트 환경에서의 구동 방법, 콘텐츠 제작 방법, 환경 변수, 자주 막히는 점까지 포함하는 문서가 되어 있었습니다.
여기까지만 해도 상세한 리포지토리 해설의 범위라고 할 수 있습니다. 예상 밖이었던 것은, 호스트에서 직접 구동하는 절차에 다음 설명이 있었다는 것입니다.
이 절차는 저희 검증 환경(Linux, Go 1.26.0)에서 실제로 끝까지 통과시키고, 테스트 전 합격 및 업로드 성공,
/display가
closed시니를 반환하는 것을 확인했습니다. 참고로 Node 22에서도 빌드 자체는 통과했습니다.
게다가 콘텐츠 설명에는 '어서 오세요'라는 일본어로 대체되어 수리된 것까지 기록되어 있었습니다.
즉, Claude는 소스 코드를 읽고 그럴듯한 절차를 조합했을 뿐만 아니라. 적어도 생성된 문서에서는 Linux 환경에서 다음 결과를 확인했음이 알 수 있습니다.
GET /display에서 기대한 시니를 얻을 수 있었다. - 일본어를 포함한 콘텐츠가 검증을 통과했다.
다만, 여기는 신중하게 구분하고 싶습니다. 이번에는 Claude의 상세 작업 로그를 저장하지 않았기 때문에, 어떤 순서로 무엇을 생각했고 어떤 명령어를 실행했는지까지 단정할 수는 없습니다. 확인할 수 있는 것은, 생성된 문서가 검증 환경과 결과를 명시하고 있다는 점, 그리고 요청한 프롬프트에 Linux에서의 동작 확인이 포함되어 있지 않았다는 것입니다.
생성된 문서에서 인상적이었던 것은, 정상적인 절차뿐만 아니라 이용자가 막힐 만한 점들이 정리되어 있었다는 것입니다.
예를 들어, 다음과 같은 주의사항이 있습니다.
/display가
204 No Content
그렇다면, 표시의 오류가 아니라 콘텐츠가 아직 공개되지 않은 것일 수 있다. 화면이 초기 상태라면, 업로드가 미진행했을 뿐만 아니라 브라우저 측의 렌더링 실패도 확인해야 한다.
한편으로, 시도하지 않은 범위도 숨기지 않았다.
이쪽 검증 환경에서는 Docker 데몬을 사용할 수 없었기 때문에, 방법 A는 README에 근거한 절차로 실행 확인은 하지 않았다.
이는 중요한 서술이라고 생각한다. 'Docker라면 이 절차입니다'라고 쓰는 것과, 'Docker로 실제로 확인했다'고 쓰는 것을 분리하고 있기 때문이다.
나중에 제작을 의뢰한 AI 에이전트용 조작 가이드인 'Glypha를 AI 에이전트로 구동하기'에서도 같은 태도가 나타났다. JSON과 이미지를 실제로 업로드하여 HTTP 200이 반환되고 일본어가 표시된 예는 검증 완료라고 명시하는 한편, Claude Code나 Codex와의 대화 자체는 해당 환경에서는 시도하지 않았다고 적혀 있다.
게다가 'Glypha에 Playwright를 도입하기(macOS / Windows WSL)'에서는 Linux 환경에서 4개의 테스트가 통과했고, Playwright MCP로 스크린샷을 찍을 수 있었다고 기재하면서도, macOS와 WSL 실기에서는 미검증임을 명시했다.
이 '어디까지 확인했고, 어디부터는 자료에 근거한 설명인가'라는 경계는 기술 문서의 신뢰성을 크게 좌우한다. 적어도 이번 산출물은 모든 것을 검증 완료된 것처럼 다루지 않았다.
이번에 만들어진 문서는 기존 영어 문서를 일본어로 단순히 대체한 것만은 아니다.
리포지토리 내의 정보를 사용자가 따라가는 순서로 재배열하고 있다. 먼저 무엇을 준비해야 하는지, 어디에서 명령어를 실행해야 하는지, 어떤 응답이 성공인지, 실패했을 때 어디를 봐야 하는지 등이다. 코드 구조 설명도 단순한 파일 목록이 아니라, 업로드된 콘텐츠가 검증되고 저장되며 표시되는 흐름으로 구성되어 있었다.
여기에 실행 결과가 더해지면서, 문서는 '코드로부터 추론한 설명'에서 '적어도 하나의 환경에서 통과한 이용 절차'로 바뀌었다.
이는 문서 생성에서의 AI 에이전트의 역할을 조금 다르게 보여준다.
글을 쓰기 전에 대상을 사용해 본다. 작동하지 않으면 오류를 읽는다. 작동한 범위와 작동시키지 못한 범위를 나눈다. 그리고 그 경험을 이용자의 절차로 되돌린다.
인간 테크니컬 라이터나 개발자라면 자연스럽게 하는 일이지만, 이번에 Claude도 결과적으로 이에 가까운 일을 하고 있었다.
이번에 인간이 제공한 것은 '일본어로 코드 설명/원리/사용 방법을 정리해 달라'는 목적과 산출물의 이미지였다. 조사 절차까지 지정하지 않았다.
그럼에도 불구하고, 생성물에는 실행 확인이 포함되었다.
여기서 'AI에게는 세세한 지시가 불필요하다'라고 일반화하는 것은 빠르다. 리포지토리의 상태, 이용 가능한 실행 환경, 권한, 모델, 의뢰 작성 방식에 따라 행동은 달라진다. 이번에는 작업 로그도 남기지 않았기 때문에, Claude가 왜 Linux에서의 확인을 선택했는지 그 판단 과정도 알 수 없다.
하지만 하나의 협업 방식이 보인다고 생각한다.
인간은 달성하고자 하는 목적, 산출물의 독자, 지켜야 할 경계를 전달한다. 그 위에서 리포지토리를 읽고, 테스트하고, 구동하고, 결과를 비교하는 것과 같은 조사 방법에는 여백을 남긴다. AI 에이전트가 그 여백을 사용할 수 있는 환경이라면, 인간이 처음부터 모든 절차를 설계하는 것보다 목적에 필요한 확인을 스스로 구성할 가능성이 있다.
물론, 맡겨두기만 할 수는 없다. 이번처럼 실행 완료와 미실행을 나누어 읽는 것, 외부 공개나 데이터 삭제 같은 조작에는 명확한 제한을 두는 것, 중요한 주장은 로그나 테스트 결과를 남기는 것이 필요하다.
Glypha는 AI 에이전트에게 자유로운 조작을 허용하는 동시에, 수용 가능한 상태를 시스템 측에서 제한하도록 만들었다.
AI가 생성한 콘텐츠에 문제가 있으면 API가 구체적인 오류를 반환한다. AI는 그것을 읽고 수정할 수 있다. 올바른 것이 완성될 때까지 현재의 표시는 망가지지 않는다. 조작을 한 단계씩 가르치는 것이 아니라, 넘어서는 안 될 경계를 소프트웨어 측에 두는 설계이다.
이번 문서 작성도 그와 비슷한 형태가 되었다. 인간은 목적을 제시했고, 상세한 탐색 절차를 고정하지 않았다. 그 결과, Claude는 문서를 쓰기 위해 필요한 확인까지 작업 범위를 넓혔다.
이것은 한 번의 실험이며, AI가 소프트웨어를 '이해했다'고까지 말할 수는 없다. 그럼에도 불구하고, 코드를 설명하는 것뿐만 아니라 이용자로서 소프트웨어에 접촉하고 그 결과를 문서에 반영한 것은 관찰할 수 있었다.
새로운 소프트웨어의 첫 이용자는 대개 개발자 자신이다. 따라서, 전제 지식이 없는 사람이 어디에서 어려움을 겪을지 놓치기 쉽다.
만약 AI 에이전트에게 구현이 끝난 단계에서 '처음 사용하는 사람을 위한 문서를 만들어 달라'고 요청하고, 실제로 격리된 환경에서 실행 및 조작 및 검증까지 시킨다면 어떨까?
AI는 문서의 집필자일 뿐만 아니라, 최초 이용자, 스모크 테스트(Smoke Test) 실행자, 이해하기 어려운 전제를 찾아내는 관찰자 역할도 할 수 있을지도 모른다.
이번에 알게 된 것은 그 가능성이라는 지점까지이다. 재현성을 확인하려면 다음으로는 작업 로그를 저장하고, 사람이 작성한 문서와의 비교나 다른 환경에서의 재실행도 필요할 것이다.
그럼에도 불구하고, 첫 번째 요청에서는 상상하지 못했던 질문이 남았다.
AI 에이전트를 소프트웨어 개발 프로세스에 최초 이용자로서 통합할 수 있지 않을까?
문서를 작성하게 하는 실험은 어느새 누가 처음으로 소프트웨어를 사용하게 할 것인가라는 실험으로 변모하고 있었다.