에이전트 워크플로우를 위해 스킬과 커맨드를 구조화하는 방법

스킬은 지식을 담고 명령(command)은 의도(intent)를 담는다. 이 둘을 분리한 후, 나의 에이전트 워크플로우는 더 짧아지고, 반복 가능해지며, 검토하기 쉬워졌다.

공개 사항: 저는 코딩 에이전트를 위한 키트인 AgentKrew의 설립자이며, 이 예시를 전체 과정에서 사용하고 있습니다. 아이디어 자체는 이것 없이도 작동하며, 어느 지점에서 작동을 멈추는지 말씀드리겠습니다.

하나의 거대한 프롬프트가 가진 문제점

흔한 시작 방식은 모든 세션 초반에 붙여넣는 길고 방대한 단일 프롬프트입니다. 여기에 규칙(conventions), 상기 사항(reminders), 건드리지 말아야 할 목록 등을 포함합니다. 처음에는 효과를 발휘합니다. 하지만 시간이 지나면서 너무 커져서 아무도 읽지 않게 되고, 그날의 문장 구성 방식에 따라 결과가 달라집니다.

해결책은 지침을 하나의 것으로 취급하는 것을 멈추는 것입니다. 일부는 마이그레이션(migrations) 방법처럼 '지식'입니다. 일부는 "이 기능을 계획하라(plan this feature)"와 같이 '의도'입니다. 이 둘을 하나의 프롬프트에 혼합하는 것이 시스템을 불안정하게 만듭니다.

스킬: 에이전트가 가져오는 지식

스킬은 마이그레이션 방법, 인증 처리 방식, 테스트 작성 방법 등 특정 작업을 위한 재사용 가능한 일련의 지침입니다. 에이전트는 작업이 필요할 때 이 스킬을 로드합니다. 핵심은 매번 세션마다 규칙을 다시 설명하는 대신, 한 번만 작성한다는 것입니다.

스킬을 작성할 때 제가 따르는 규칙들:

• 스킬당 하나의 작업(One job per skill). 몇 마디의 말로 작업을 정의할 수 없다면, 분리해야 합니다.

• 명령이 아닌 참조(Reference, not orders). 스킬은 에이전트가 무엇을 알아야 하는지를 알려줍니다. 지금 당장 해야 할 일은 다른 곳에 두어야 합니다.

• 프로젝트 사실 정보는 여기에 보관. 청구 규칙(Billing rules), 명명 규칙(naming conventions), 그리고 절대 건드려서는 안 되는 파일들은 모두 스킬에 포함되어야 합니다.

• 검토하기에 충분히 짧게. 무언가 잘못되었을 때, 1분 안에 스킬을 읽고 원인을 찾을 수 있어야 합니다.

명령(Commands): 한 단어 진입점

명령은 반복 가능한 단계를 시작하기 위해 입력하는 짧은 키워드입니다: 계획(plan), 검토(review), 테스트(test) 등. 이는 의도(intent)를 담고 있으며, 그 의도를 수행하는 데 필요한 지식을 가리킵니다.

• 행동(action)을 주제가 아닌 이름으로 지정하세요. 'plan', 'review', 'test'는 커맨드입니다. 'migration notes'는 스킬입니다.

• 커맨드는 간결하게 유지하세요. 만약 커맨드가 너무 많은 지식을 담고 있다면, 그 지식을 스킬로 옮기고 커맨드가 이를 호출하도록 하세요.

• 한 단계에 하나씩만 처리하세요. 그것이 무엇을 하는지 한 문장으로 설명할 수 없다면, 그것은 두 개의 커맨드입니다.

유용한 테스트: 스킬은 '에이전트가 무엇을 알아야 하는가?'에 답하고, 커맨드는 '지금 무엇을 해야 하는가?'에 답합니다.

에이전트와 워크플로우가 연결고리 역할을 합니다

스킬과 커맨드 역시 실행할 주체와 순서가 필요합니다.

• **에이전트(Agents)**는 역할로 정의된 이름 있는 전문가입니다: 테크 리드, 빌더, 리뷰어, 보안 감사자 등. 각 에이전트는 라우팅 설명(routing description)을 가지고 있어 적절한 작업이 올바른 담당자에게 할당되도록 합니다. 리뷰어의 업무는 그것을 실행하는 도구가 바뀌어도 변하지 않습니다.

• **워크플로우(Workflows)**는 즉흥적인 것이 아니라 고정된 순서입니다. 테크 리드가 계획하고, 전문가들이 병렬로 빌드하며, 그 후 리뷰어, 보안 감사자, 배포 담당자가 무언가가 외부로 나가기 전에 게이트 역할을 합니다.

순서가 고정되어 있기 때문에, 동일한 워크플로우를 두 번 실행해도 같은 단계를 따릅니다. 이 예측 가능성이 핵심입니다: 즉흥적인 결정의 흐름이 아니라 계획과 통제된 결과물을 검토하는 것입니다.

모든 도구에 대한 단일 진실 공급원(Single source of truth)

여러 개의 코딩 에이전트를 사용하면 지침 파일들이 분산됩니다. 처음에는 동일했던 두 파일도 시간이 지나면 서로 다른 내용으로 오해하게 됩니다. 가장 저렴한 해결책은 AGENTS.md를 원본 소스로 유지하고 CLAUDE.md가 이를 참조하도록 하는 것입니다. 이렇게 하면 편집할 곳이 하나만 생깁니다.

AgentKrew는 이 아이디어를 더 발전시켰습니다. 동일한 키트(kit)가 Claude Code, Codex, OpenCode로 렌더링되므로, 정의하는 역할과 워크플로우가 어떤 도구가 실행하느냐에 의존하지 않습니다.

모든 워크플로우를 배포 게이트로 마무리하세요

워크플로우의 마지막 단계는 '좋아 보인다'여서는 안 됩니다. 타입 체크(type check), 테스트, 린트(lint), 빌드를 실행하고 준비되었거나 차단되었다는 두 가지 답변 중 하나를 반환하는 검사여야 합니다.

게이트는 어떤 도구가 코드를 작성했는지와 상관없이 작동합니다. 오직 결과만을 보기 때문입니다. 또한 인간이 개입할 수 있는 명확한 순간을 제공합니다. 막힌(blocked) 결과는 무언가를 배포하기 전에 무엇이 실패했는지 알려주며, 문제를 숨기는 초록색으로 보이는 diff(차이점)와는 다릅니다.

필요한 부분이 어떤 것인지 빠르게 결정하는 방법

각 부분은 서로 다른 질문에 답합니다. 만약 지침이 어떤 질문에 답하는지 말할 수 없다면, 분리하세요.

한계점, 그리고 AgentKrew의 역할

에이전트는 세션 사이에 학습하지 않습니다. 인간 동료는 6개월 후에도 청구 모듈을 기억하지만, 에이전트는 매번 처음부터 시작합니다. 컨텍스트를 Skill과 파일에 넣는 것은 임시방편이며, 여전히 해당 파일을 유지해야 합니다. 이를 코드처럼 취급하고 변경 사항을 검토하세요.

별도의 리뷰어(reviewer)가 도움이 되지만, 신뢰할 수 있는 테스트를 대체하지는 못합니다. 어떤 도구를 사용하든, 누가 테스트를 작성하는지 확인하세요. 만약 한 사람이 코드를 작성하고 자체 어설션(assertions)까지 한다면, 초록색 실행 결과는 거의 아무것도 증명하지 못합니다.

AgentKrew는 이 구조(에이전트, 스킬, 커맨드, 워크플로우)를 하나로 패키징하려는 저의 시도입니다. 버전 관리되고 검증된 키트로 구성되어 Claude Code, Codex, OpenCode로 렌더링되며, 사용자의 파일에는 영향을 주지 않으면서 업데이트됩니다. 확인하고 싶다면 agentkrew.com에 있습니다. 무엇이 빠져 있는지 듣고 싶습니다.