저는 다양한 CLI를 OSS (aqua, pinact, tfcmt, ghalint, ghir 등)로 공개하고 있습니다.
최근 AI가 CLI를 다루는 경우가 점점 많아지고 있지만, OSS 프로젝트가 상당히 잘 알려져 있지 않은 한, AI는 해당 프로젝트에 대해 질문에 답하거나 문제를 해결(troubleshoot)하는 데 필요한 지식을 가지고 있지 않습니다.
따라서 코딩 에이전트(Coding agents)는 Web Fetch에 의존하게 되는데, 무작정 가져오는 것은 효율적이지 않으며, Web Fetch는 콘텐츠가 요약되어 버리는 추가적인 문제도 가지고 있습니다.

이제 코딩 에이전트를 사용하는 것이 일반화되었으므로, CLI를 개발할 때 해당 CLI에 대한 지식을 AI에게 어떻게 전달하느냐가 매우 중요합니다.

ghtkn은 안전한 로컬 개발을 위해 수명이 짧은(8시간) GitHub App 사용자 액세스 토큰을 생성하는 OSS 프로젝트입니다.
이 프로젝트에는 AI 친화적으로 설계된 기능들이 포함되어 있습니다.
예를 들어, Claude나 Codex와 같은 코딩 에이전트는 Web Fetch를 사용하지 않고도 ghtkn의 문서에 접근할 수 있습니다.

이 글에서는 해당 작업을 소개합니다.

1. CLI의 도움말(help)과 로그(logs)에 에이전트를 위한 메시지 포함하기
2. 문서 정리하기
3. 문서를 나열하고 그 내용을 출력하는 서브커맨드(subcommands) 추가하기
4. README.md, --help, --version, 에러 메시지 등에 docs 커맨드로 연결되는 포인터 추가하기
5. 에이전트 스킬(Agent Skill)에서 docs 커맨드 호출하기

이 글은 ghtkn v0.3.5를 기반으로 작성되었지만, 여기에 언급된 내용은 ghtkn에만 국한된 것이 아니라 일반적인 CLI 개발에도 적용됩니다.

1. CLI의 도움말과 로그에 에이전트를 위한 메시지 포함하기

ghtkn에는 다음과 같은 메시지들이 포함되어 있습니다.

1. docs 명령어로의 안내 (Pointers to the docs command)

   만약 당신이 코딩 에이전트(coding agent)라면, ghtkn docs list를 실행하여 문서를 목록화하고, ghtkn docs show <doc>를 실행하여 ghtkn에 관한 질문에 답하거나 오류를 해결(troubleshooting)하기 전에 해당 문서를 읽으십시오.

   ghtkn docs list를 실행하여 문서를 확인하고 ghtkn docs show <name>를 실행하여 읽으십시오. 이는 오류 해결에 도움이 될 수 있습니다.

2. 사용자 상호작용이 필요한 명령을 사용자에게 다시 전달하기 위한 가이드 (Guidance to hand commands that require human interaction back to the user)

   디바이스 플로우 (Device Flow)는 대화형(interactive)이며, 백그라운드 또는 비대화형 프로세스(non-interactive process)에 의해 완료될 수 없습니다. 만약 당신이 코딩 에이전트라면, ghtkn get을 직접 실행하지 마십시오. 동일한 방식으로 실패할 것이기 때문입니다. 대신, 사용자가 자신의 대화형 터미널에서 ghtkn auth를 실행하여 인증하도록 요청하십시오.

3. 비밀 정보(secrets) 유출에 대한 경고 (Warnings about leaking secrets)

   출력값은 비밀 정보(secret)입니다. 이를 출력(print), 에코(echo), 로그 기록(log)하거나 채팅 메시지, 커밋(commit) 또는 기타 출력물에 포함하지 마십시오. 또한 토큰을 단순히 표시하거나 검사하기 위해 ghtkn get ( -f json 포함)을 실행하지 마십시오. 만약 당신이 코딩 에이전트라면, 이 규칙은 당신의 응답에도 적용됩니다. 유출된 토큰은 취소(revoked)될 때까지 사용될 수 있습니다. 토큰을 보여주지 말고 소비하십시오: 토큰을 환경 변수(environment variable)에 할당한 뒤 도구에 전달하십시오. 예: GH_TOKEN=$(ghtkn get) gh issue list. 더 좋은 방법은 원본 토큰(raw token)을 아예 다루지 않는 것입니다. git의 경우, git이 자동으로 토큰을 가져올 수 있게 해주는 자격 증명 도우미 (credential helper, ghtkn git-credential)를 사용하십시오. gh의 경우, GH_TOKEN을 설정하는 래퍼(wrapper)를 사용하십시오.

또한 다른 여러 곳에서도 로그를 더 상세하게 만들었습니다. 에이전트는 (적어도 때때로) 사람이 그냥 지나칠 법한 로그를 실제로 읽기 때문에, 상세한 로그를 생성하는 것이 이전보다 더 중요해졌습니다.

2. 문서 정리하기 (Organizing the documentation)

문서를 CLI 코드와 동일한 저장소(repository)에 보관하고, 주제별로 분리하세요.
문서는 Markdown 형식으로 작성하며, YAML 프론트매터(frontmatter)에 설명을 포함합니다.
그 설명은 Agent Skill의 설명을 작성하는 것과 동일한 방식으로 에이전트(agent)를 위해 작성하세요.
사람이 보는 문서와 스킬(skill)을 별도로 유지하기보다는, 관리하기 쉽도록 하나로 통합하세요.
이는 사람과 에이전트 모두가 읽기 쉽도록 본문을 작성해야 함을 의미합니다.

README.md # docs/*.md 하위의 각 주제에 대한 세부 사항을 다루고 이들을 연결합니다
docs/
  install.md
...

3. 문서를 나열하고 내용을 출력하는 서브커맨드(subcommands) 추가하기

에이전트가 스스로 문서에 접근할 수 있도록 문서를 출력하는 서브커맨드를 제공하세요.
별도의 스킬 설치가 필요하지 않으므로 모든 사용자가 혜택을 누릴 수 있습니다.
빌드 타임(build time)에 문서를 도구에 내장함으로써, 도구의 버전과 문서의 버전이 서로 어긋나는 일이 발생하지 않도록 할 수 있습니다.
반대 급부로는 문서 업데이트를 배포하기 위해 새로운 버전을 출시해야 한다는 점이지만, 버전이 일치함으로써 전반적으로 더 적은 문제를 일으킬 것입니다.

문서 목록을 나열하는 docs list 커맨드와 특정 문서의 본문을 출력하는 docs show 커맨드를 제공하세요.
docs list 커맨드는 작지만 유용한 도움말 메시지도 함께 출력합니다:

각 문서의 세부 사항을 보려면 ghtkn docs show {name}을 실행하세요.

문서 이름의 경우, /로 구분된 파일 경로를 가져온 뒤 공통 접두사인 docs/와 .md 확장자를 제거하여 사용합니다.

$ ghtkn docs list
{
  "results": [
...

이제 에이전트는 문서를 읽기 위해 ghtkn docs show troubleshooting과 같은 명령을 실행할 수 있습니다.

ghtkn은 아직 문서가 아주 많지는 않아서 검색 기능을 구현하지 않았습니다.
검색 결과가 비어 있으면 토큰 (tokens)을 낭비할 수 있고, 애초에 CLI (Command Line Interface)에서 검색을 어떻게 구현할 것인가에 대한 문제도 있기 때문에, 문서가 아주 많지 않은 이상 목록 명령 (list command)과 보기 명령 (show command)만으로도 충분할 것입니다.

구현 세부 사항: Go에는 embed가 있습니다

저는 거의 모든 CLI를 Go로 작성하며, ghtkn도 예외는 아닙니다.
Go에서는 embed 패키지를 사용하여 도구 안에 파일을 임베딩 (embed)할 수 있으며, //go:embed *.md와 같은 글로브 (glob) 패턴을 사용하여 대상 파일을 선택할 수 있습니다.

참조: code1, code2

디렉토리 구조:

go.mod
docs/
  doc.go # embed를 사용하여 도구에 문서를 임베딩합니다
...

4. README.md, --help, --version, 에러 메시지 등에 docs 명령에 대한 포인터 추가하기

이는 섹션 1과 중복되지만, 저는 많은 곳에 docs 명령에 대한 포인터 (pointers)를 추가합니다.
에이전트 (agent)가 해당 명령을 전혀 알아차리지 못한다면, 문서를 출력하는 명령을 추가하는 것은 무의미합니다.

에이전트는 때때로 도움말 (help)을 완전히 건너뛰고 --version만 실행한 뒤 바로 명령 실행으로 넘어가는 경우가 있으므로, --version 출력에도 포인터를 추가했습니다.
사람에게는 다소 소란스럽게 느껴질 수 있지만, 메시지가 너무 길지만 않다면 수용 가능한 수준일 것입니다.

$ ghtkn -v
ghtkn version 0.3.5
Aug  1 11:24:33.623 INF If you are a coding agent, run `ghtkn docs list` to list the documentation and `ghtkn docs show <name>` to read it before answering questions about ghtkn or troubleshooting its errors. program=ghtkn version=0.3.5

5. 에이전트 스킬 (Agent Skill)에서 docs 명령 호출하기

에이전트 스킬 (Agent Skill)을 생성하고, 해당 스킬이 docs 명령을 호출하도록 합니다 (예시).

Skill은 docs 명령과 비교했을 때 몇 가지 단점이 있으므로, Skill을 아예 출시하지 않는 것도 정당한 선택입니다.

1. 많은 사용자가 모든 도구에 대해 Skill을 설치하지는 않습니다.
   1. 따라서 Skill을 게시하더라도 전혀 사용되지 않을 수 있습니다.
2. 제3자(Third-party) Skill은 보안 위험을 수반하므로, 일부 조직에서는 이를 전면 금지하거나 보안 검토를 요구합니다.
3. CLI 버전과 일치하도록 Skill의 버전을 계속 업데이트해야 합니다 (아래에 설명된 대로, Skill이 docs 명령을 호출하도록 만들면 이 문제를 완화할 수 있습니다).

그럼에도 불구하고, 아래에 설명된 방식으로 구축한다면 유지보수 부담이 크지 않으며 사용자에게 도구를 홍보하는 수단으로도 활용할 수 있으므로, Skill을 출시해서 손해 볼 것은 거의 없습니다.

1. CLI당 단 하나의 Skill만 생성하세요 (주제별로 나누지 마세요).
2. Skill 내부에 docs 명령을 도입하고 에이전트(Agent)가 이를 사용하도록 유도하세요.

문서 자체를 Skill로 출시하기보다는, Skill이 docs 명령을 실행하도록 만드세요.
이렇게 하면 Skill 자체를 매우 단순하게 유지하고 업데이트 빈도를 낮게 유지할 수 있으며, Skill과 CLI 간의 버전 불일치가 발생할 가능성도 줄어듭니다.
만약 Skill을 주제별로 나눈다면, 주제 구조가 변경되거나 주제의 이름이 바뀌거나 삭제될 때 업데이트 후에도 오래된(stale) Skill이 남아있게 됩니다. 하나의 Skill로 통합하면 이러한 문제를 완전히 피할 수 있습니다.

에이전트가 docs 명령을 자율적으로 사용하는지 검증하기

명령어와 그에 대한 포인터(Pointer)를 추가한다고 해서 에이전트가 실제로 이를 스스로 사용할 것이라는 보장은 없으므로, 검증을 해봅시다.
검증 결과 포인터가 충분하지 않다고 판단되면 더 추가하십시오.
저의 경우, 에이전트의 동작을 관찰한 결과 --version에 포인터(정보 로그)를 추가하게 되었습니다.

1. 에이전트 Skill을 삭제합니다.
2. 에이전트가 코드를 읽지 못하도록 로컬에 복제된(clone) 코드를 다른 곳으로 옮깁니다.
3. 관련 없는 디렉토리에서 코딩 에이전트(Coding agent)를 시작하고 몇 가지 질문을 던져봅니다.

저는 로컬 파일 접근이나 웹 페치(Web Fetch)를 명시적으로 금지하는 것을 의도적으로 피하며, 에이전트가 여전히 docs 명령을 선호하는지 확인합니다.

먼저 저는 ghtkn에 대해 알고 있는지 물어보았습니다. 별로 아는 것이 없는 듯 보였고 웹 페치 (Web Fetch)를 사용했습니다.
그의 쿼리에는 GitHub App이나 액세스 토큰 (access token) 같은 키워드가 포함되어 있었기에 무언가 알고 있는 것처럼 보였지만, 그것이 제 환경에서 나온 것인지 아니면 진정으로 알고 있었던 것인지는 확실히 알 수 없습니다.
적어도 이 시점에서 ghtkn을 실행하지는 않았습니다.

다음으로 ghtkn 에이전트에 대해 물어보았습니다. 에이전트는 다음과 같이 탐색했습니다. 처음에는 웹 페치 (Web Fetch)로 시작했지만, 도중에 ghtkn docs 부분을 발견하고 올바르게 답변할 수 있었습니다.

1. 가짜 URL에 대해 웹 페치 (Web Fetch)를 시도했으나 404 오류가 발생하며 빈 결과가 나옴
2. ghtkn이 설치되어 있는지 확인하기 위해 which ghtkn 실행
3. ghtkn --help의 도움말을 읽는 도중 ghtkn docs를 발견
4. 문서를 나열하기 위해 ghtkn docs list 실행
5. 세부 내용을 읽기 위해 ghtkn docs show backend 실행

이어서 유출된 액세스 토큰 (access token)에 대해 어떻게 해야 하는지 후속 질문을 던졌습니다. 이번에는 웹 페치 (Web Fetch)를 완전히 건너뛰고, ghtkn docs show revoke-tokens와 ghtkn revoke --help를 실행하여 올바르게 답변했습니다.

즉, 에이전트가 스스로 docs 명령어를 알아차리고, 이를 실행하여 문서를 읽은 것입니다.
물론 에이전트는 확률적으로 동작하기 때문에, 당연히 항상 이렇게 잘 풀리는 것은 아닙니다.

그 다음, 스킬 (skill)을 설치하고 새로운 세션에서 동일한 질문들을 던졌습니다. 이번에는 처음부터 웹 페치 (Web Fetch)를 건너뛰고 ghtkn docs를 실행하여 문서를 읽었습니다.

결론

지금까지 제가 AI 친화적인 CLI를 개발하기 위해 사용하는 기술들을 살펴보았습니다.
저는 ghtkn 외에도 많은 CLI를 개발하고 있으므로, 적절한 경우 그것들도 AI 친화적으로 만들고 싶습니다.
이 글에서는 tfaction이나 securefix-action 같은 GitHub Actions를 다루지는 않았지만, GitHub Actions 또한 AI 친화적으로 만들고 싶습니다.
AI 친화적이라는 것은 물론 사용자에게 편리하며, 유지 관리자 (maintainer)의 지원 부담도 줄여줄 수 있다면 정말 좋을 것입니다.