코딩 에이전트(Coding agents)는 이제 저장소(repositories)를 조사하고, 테스트를 작성하며, CI를 구성하고, 프레임워크를 마이그레이션하며, 버그를 수정할 수 있습니다.

하지만 우리가 에이전트에게 부여하는 워크플로(workflows)는 종종 놀라울 정도로 비정형적입니다.

우리는 이전 대화, 내부 문서, GitHub 이슈 또는 무작위 텍스트 파일에서 프롬프트(prompts)를 복사합니다. 그런 다음 현재 프로젝트에 맞게 해당 프롬프트를 수정하며, 중요한 지침을 삭제하지 않았기를 바랍니다.

이 점이 저를 궁금하게 만들었습니다:

코딩 에이전트 작업(coding-agent task)을 패키지(package)처럼 설치, 조사, 버전 관리 및 실행할 수 있다면 어떨까?

저는 이 아이디어를 탐구하기 위해 Clawx를 구축했습니다.

🔗 GitHub에서 Clawx 보기

Clawx란 무엇인가?

Clawx는 재사용 가능한 코딩 에이전트 작업을 위한 오픈 소스 패키지 매니저(package manager)입니다.

패키지는 YAML 메타데이터(metadata)가 포함된 Markdown 파일입니다.

Markdown에는 코딩 에이전트를 위한 지침(instructions)이 포함되어 있습니다. 메타데이터는 다음과 같은 정보를 설명합니다:

• 패키지 이름 및 버전
• 필수 파라미터(parameters)
• 환경 변수(Environment variables)
• 의존성(Dependencies)
• 요청된 도구(tools)
• 지원되는 에이전트 제공자(agent providers)

기본적인 워크플로는 다음과 같습니다:

clawx search gitignore
clawx info gitignore-gen
clawx run gitignore-gen

작업을 실행하기 전에, Clawx는 사용자가 패키지에 무엇이 포함되어 있는지, 어떤 기능(capabilities)이 필요할 수 있는지를 조사할 수 있게 해줍니다.

실행 후에는 실행 기록이 저장됩니다:

clawx history

목표는 에이전트 워크플로를 더 쉽게 발견, 검토, 재사용 및 감사(audit)할 수 있도록 만드는 것입니다.

재사용 가능한 프롬프트의 문제점

유용한 프롬프트를 저장하는 것은 이미 좋은 관행입니다.

하지만 프롬프트가 포함된 텍스트 파일은 보통 다음과 같은 질문에 답하지 못합니다:

• 내가 실행 중인 버전은 무엇인가?
• 내용이 변경되었는가?
• 에이전트가 어떤 도구(tools)를 사용할 수 있는가?
• 어떤 입력값(inputs)이 필요한가?
• 다른 작업이 먼저 실행되어야 하는가?
• 지난번에 무엇이 실행되었는가?
• 다른 개발자가 이 워크플로를 재현할 수 있는가?

프롬프트는 종종 작업을 포함하지만, 작업 주변의 운영 구조(operational structure)는 포함하지 않습니다.

Clawx는 에이전트 지침을 일회성 채팅 메시지가 아닌 버전 관리되는 아티팩트(artifacts)로 취급합니다.

패키지는 어떤 모습인가요?

간소화된 Clawx 패키지는 다음과 같은 모습일 수 있습니다:

---
name: repo-health-check
version: 1.0.0
...

이 패키지는 Clawx 없이도 읽을 수 있는 상태로 유지됩니다.

이는 중요한 설계 결정이었습니다.

핵심 동작이 복잡한 바이너리 형식(binary format)이나 설정 언어(configuration language) 안에 숨겨지는 것을 원하지 않았습니다. 개발자는 일반적인 Git diff를 통해 패키지를 검토할 수 있어야 합니다.

실행 방식

사용자가 패키지를 실행하면 Clawx는 여러 단계를 수행합니다.

1. 패키지 해석 (Resolve)

Clawx는 설정된 레지스트리(registry)에서 패키지를 찾습니다.

레지스트리는 Git 저장소(repository)나 HTTP 서비스로 구현될 수 있습니다.

2. 콘텐츠 검증

다운로드된 패키지는 예상되는 SHA-256 체크섬(checksum)과 비교됩니다.

이를 통해 레지스트리 메타데이터와 검색된 패키지 사이의 예기치 않은 변경 사항을 감지할 수 있습니다.

하지만 체크섬이 패키지의 안전성을 증명하는 것은 아닙니다.

그것은 단지 다운로드된 콘텐츠가 예상된 콘텐츠와 일치한다는 것만을 증명할 뿐입니다.

3. 실행 요청 표시

에이전트를 시작하기 전에 Clawx는 다음과 같은 세부 정보를 표시할 수 있습니다:

• 패키지 이름
• 버전
• 파라미터 (Parameters)
• 환경 요구 사항 (Environment requirements)
• 요청된 도구 (Requested tools)
• 선택된 에이전트 제공자 (Agent provider)

사용자는 실행을 승인하기 전에 이 정보를 검토할 수 있습니다.

4. 코딩 에이전트 호출

Markdown 지침이 지원되는 코딩 에이전트 CLI(command-line interface)로 전달됩니다.

Clawx는 다음과 같은 도구들을 포함하여 여러 제공자(providers)와 함께 작동하도록 설계되었습니다:

• Claude Code
• Codex
• Gemini CLI
• OpenCode
• Antigravity

5. 결과 기록

Clawx는 실행 이력(execution history)을 보관하여 사용자가 이전 실행 내용을 검사할 수 있도록 합니다.

왜 쉘 스크립트(shell script)를 사용하지 않나요?

쉘 스크립트는 결정론적 자동화(deterministic automation)에 더 적합합니다.

예를 들어, 항상 다음과 같은 올바른 프로세스가 수행되어야 하는 경우:

npm install
npm test
npm run build

대개 에이전트를 개입시킬 이유가 없습니다.

에이전트 기반 패키지는 작업이 저장소 컨텍스트(repository context)에 의존할 때 더욱 유용해집니다.

다음과 같은 요청을 생각해 보십시오:

이 저장소를 조사하여 언어와 빌드 시스템(build system)을 파악하고, 적절한 CI 워크플로(workflow)를 구성한 뒤, 사용 가능한 체크(checks)를 실행하고, 당신의 결정 사항을 설명하십시오.

결정론적인 스크립트(deterministic script)라면 가능한 많은 프레임워크(frameworks), 레이아웃(layouts), 패키지 매니저(package managers), 그리고 테스트 시스템(test systems)을 미리 예측해야 할 것입니다.

코딩 에이전트(coding agent)는 저장소를 조사하고 그에 맞춰 적응할 수 있습니다.

Clawx는 셸 스크립트(shell scripts), Makefile, Ansible, Terraform 또는 CI 시스템을 대체하기 위해 만들어진 것이 아닙니다.

Clawx는 다른 범주를 탐구합니다:

해석(interpretation)과 프로젝트 컨텍스트(project context)가 중요한 재사용 가능한 작업(reusable tasks).

왜 여러 에이전트를 지원해야 하는가?

저는 유용한 작업이 특정 제공자(provider)에 영구적으로 종속되는 것을 원하지 않았습니다.

Dockerfile을 감사(auditing)하거나 CI를 구성하는 패키지는, 팀이 선호하는 코딩 에이전트를 변경하더라도 이상적으로는 계속 유용하게 유지되어야 합니다.

하지만 제공자 독립성(provider independence)에는 한계가 있습니다.

에이전트마다 동작 방식이 다릅니다. 에이전트들은 다음과 같은 요소들이 서로 다릅니다:

• 권한 모델 (Permission models)
• 도구 이름 (Tool names)
• 샌드박싱 기능 (Sandboxing capabilities)
• 컨텍스트 제한 (Context limits)
• 출력 형식 (Output formats)
• 비대화형 모드 (Non-interactive modes)
• 에러 처리 동작 (Error-handling behavior)

Clawx는 패키지 형식과 호출 프로세스를 표준화(normalize)할 수 있습니다.

하지만 모든 에이전트에서 동일한 결과를 보장할 수는 없습니다.

보안이 가장 어려운 부분입니다

지침을 다운로드하여 에이전트에게 전달하는 모든 도구는 세심한 검토를 거쳐야 합니다.

Clawx는 현재 다음과 같은 메커니즘을 제공합니다:

• 사람이 읽을 수 있는 패키지 (Human-readable packages)
• SHA-256 검증 (SHA-256 verification)
• 실행 전 승인 (Approval before execution)
• 선언된 도구 요구사항 (Declared tool requirements)
• 실행 이력 (Execution history)
• 제공자 권한 시스템과의 통합 (Integration with provider permission systems)

그러나 이러한 메커니즘이 신뢰할 수 없는 패키지를 안전하게 만들어주는 것은 아닙니다.

또한 도구 강제(tool enforcement)와 관련하여 중요한 한계가 있습니다.

일부 제공자의 경우, Clawx는 서브프로세스 경계(subprocess boundary)에서 제한 사항을 강제할 수 있습니다. 다른 제공자의 경우, 선언된 도구 목록은 주로 승인 과정에서의 정보로만 사용될 수 있으며, 실제 강제 여부는 제공자 자체의 샌드박스 및 권한 시스템에 달려 있습니다.

현재 프로젝트를 완전한 보안 경계(security boundary)로 취급해서는 안 됩니다.

일부 장기적인 질문들은 다음과 같습니다:

• 패키지에 암호화 서명 (cryptographically signed)을 해야 할까요?
• 발행자 식별 (publisher identity)은 어떻게 작동해야 할까요?
• 권한 (permissions)이 권한 기반 (capability-based)일 수 있을까요?
• 레지스트리 (registries)는 패키지를 어떻게 검토해야 할까요?
• 에이전트 실행 (agent execution)이 재현 가능 (reproducible)할 수 있을까요?
• 사용자는 패키지의 신뢰성을 어떻게 평가해야 할까요?
• 패키지의 동작이 변경되면 어떻게 되어야 할까요?

이러한 질문들은 부차적인 세부 사항이 아닙니다. 이 아이디어의 핵심입니다.

어떤 종류의 패키지가 유용할 수 있을까요?

몇 가지 예시가 있습니다.

저장소 상태 점검 (Repository health check)

프로젝트를 조사하여 다음을 포함하는 보고서를 생성합니다:

• 테스트 (Tests)
• CI (지속적 통합)
• 문서화 (Documentation)
• 의존성 (Dependencies)
• 보안 (Security)
• 유지보수성 (Maintainability)

GitHub Actions 설정

언어와 빌드 도구를 감지한 다음, 적절한 CI 워크플로 (workflow)를 생성합니다.

Dockerfile 감사 (audit)

다음 사항을 검토합니다:

• 이미지 크기 (Image size)
• 레이어 캐싱 (Layer caching)
• 사용자 권한 (User permissions)
• 의존성 설치 (Dependency installation)
• 보안 관행 (Security practices)

오픈 소스 릴리스 준비

프로젝트에 다음 사항이 있는지 확인합니다:

• 라이선스 (License)
• 기여 가이드라인 (Contribution guidelines)
• 릴리스 노트 (Release notes)
• 변경 이력 (Changelog)
• 이슈 템플릿 (Issue templates)
• 보안 문서 (Security documentation)

프레임워크 마이그레이션 (Framework migration)

기존 프로젝트를 조사하고, 마이그레이션 계획을 수립하며, 변경 사항을 점진적으로 적용하고, 결과를 검증합니다.

각 저장소마다 다르기 때문에 이러한 작업들을 보편적인 스크립트로 만드는 것은 어렵습니다.

Clawx를 구축하며 배운 점

사람이 읽을 수 있는 형식이 중요합니다

마크다운 (Markdown)을 사용하면 패키지를 조사하기가 쉬워집니다.

메타데이터 (metadata)는 구조를 제공하지만, 실제 작업은 파일을 검토하는 개발자가 이해할 수 있는 상태로 유지됩니다.

체크섬 (checksum)은 신뢰 시스템이 아닙니다

콘텐츠의 무결성 (integrity)을 검증하는 것은 유용합니다.

하지만 그것이 콘텐츠를 신뢰해야 하는지에 대한 답을 주지는 않습니다.

그것들은 별개의 문제입니다.

승인 (Approval)은 제품의 일부입니다

에이전트 도구의 경우, 실행 전의 인터페이스는 실행 자체만큼이나 중요합니다.

좋은 승인 화면은 사용자가 다음을 이해하도록 도와야 합니다:

• 무엇이 실행되는가
• 어떤 정보가 필요한가
• 어떤 도구(tools)가 사용될 수 있는가
• 저장소(repository)에서 무엇이 변경될 수 있는가

좋은 패키지는 좁은 범위의 결과(narrow outcomes)를 필요로 합니다

다음과 같이 말하는 패키지는:

이 저장소를 개선하세요.

너무 모호합니다.

더 강력한 패키지는 다음을 정의합니다:

• 구체적인 결과 (specific outcome)
• 명시적인 제약 조건 (explicit constraints)
• 검증 단계 (validation steps)
• 예상되는 파일들 (expected files)
• 실패 시 동작 (failure behavior)
• 유용한 최종 요약 (useful final summary)

패키지는 단순히 한 줄짜리 프롬프트(prompt)를 포함하는 것이 아니라, 전문 지식(expertise)을 인코딩해야 합니다.

제공자 독립성(Provider independence)은 대부분 차이점을 관리하는 것에 관한 것입니다

여러 개의 CLI를 호출하는 것이 가장 어려운 부분은 아닙니다.

어려운 부분은 각 제공자(provider)가 서로 다른 기능과 보증을 제공한다는 점을 인정하는 것입니다.

유용한 추상화(abstraction)는 이러한 차이점을 숨기기보다는 드러내야 합니다.

Clawx가 아닌 것

Clawx는 다음과 같은 것이 아닙니다:

• 결정론적 자동화(deterministic automation)의 대체제
• 다운로드된 지침이 안전하다는 보장
• 완전히 재현 가능한 빌드 시스템 (fully reproducible build system)
• 범용 샌드박스 (universal sandbox)
• 생성된 변경 사항에 대한 검토를 중단해야 할 이유
• 사용자가 맹목적으로 신뢰해야 하는 레지스트리 (registry)

Clawx는 재사용 가능한 코딩 에이전트 작업(coding-agent tasks)을 패키징하는 초기 실험입니다.

시도해보기

macOS 또는 Linux에서:

curl -fsSL https://raw.githubusercontent.com/debarshibasak/clawx/master/install.sh | sh

또한 지원되는 코딩 에이전트 CLI가 설치되어 있고 인증(authenticated)되어 있어야 합니다.

그 다음 다음을 시도해 보세요:

clawx list
clawx info gitignore-gen
clawx run gitignore-gen
...

에이전트 기반 도구는 일회용 저장소(disposable repository) 내부에서 테스트하고, 커밋(commit)하기 전에 제안된 모든 변경 사항을 검토할 것을 권장합니다.

피드백을 기다립니다

Clawx는 아직 초기 단계이며, 기술적인 비판을 기다리고 있습니다.

특히 다음 사항들에 대해:

• 코딩 에이전트 작업이 패키지로서 유용한가?
• 언제 스크립트(script)가 명확하게 더 나은 추상화가 되는가?
• 승인 화면(approval screen)에는 무엇을 보여주어야 하는가?
• 패키지 권한(permissions)은 어떻게 작동해야 하는가?
• 패키지는 제공자 독립적(provider-independent)이어야 하는가?
• 공개 레지스트리(public registry)는 어떻게 신뢰를 구축할 수 있는가?
• 실제로 어떤 작업을 설치하시겠습니까?

프로젝트는 여기서 확인하실 수 있습니다:

🔗 github.com/debarshibasak/clawx

이슈(Issues), 패키지 아이디어, 보안 피드백 및 풀 리퀘스트(pull requests)를 환영합니다.

특히 이 개념이 불필요하거나, 혼란스럽거나, 혹은 안전하지 않다고 느껴지는 부분에 대해 의견을 듣고 싶습니다.