코딩 에이전트(coding agent)는 도구를 호출하는 방법은 알 수 있지만, 변경 사항을 안전하게 만드는 엔지니어링 과정, 즉 요구사항 명확화, 계획 작성, 동작 테스트, 차이(diff) 검토, 그리고 결정 이유 기록과 같은 부분은 건너뛸 수 있습니다.

이것이 바로 에이전트 기술(agent skills)이 해결하려는 문제입니다. 기술(skill)은 단순히 더 긴 프롬프트(prompt)가 아닙니다. 그것은 지침, 예시, 선택적 스크립트, 그리고 품질 게이트(quality gates)를 갖춘 재사용 가능하고 발견 가능한 워크플로(workflow)입니다.

유용한 질문은 "모든 기술 팩을 설치해야 하는가?"가 아닙니다. 다음과 같습니다:

어떤 엔지니어링 동작이 반복 가능해져야 하며, 그것이 실행되었다는 것을 증명할 증거는 무엇인가?

이 가이드는 Addy Osmani의 agent-skills 저장소와 Agent Skills 명세(specification)를 구체적인 참조 자료로 사용합니다. 배포에 관한 조언은 저의 견해이며, 저장소의 기능과 수치는 프로젝트 문서일 뿐, 모든 팀이 동일한 결과를 얻을 것이라는 독립적인 증거는 아닙니다.

규칙 파일(rules file)을 넘어 기술이 추가하는 것

저장소의 규칙 파일(rules file)은 패키지 매니저, 테스트 명령, 아키텍처 경계, 로컬 컨벤션(conventions)과 같이 안정적인 컨텍스트(context)를 유지하는 데 유용합니다. 기술(skill)은 작업 형태의 절차(task-shaped procedure)에 더 적합합니다.

명세(specification)는 필수적인 SKILL.md와 선택적인 스크립트, 참조, 에셋(assets)을 포함하는 디렉토리를 정의합니다. 이 점진적 공개(progressive-disclosure) 모델이 중요합니다. 에이전트는 이름과 설명을 통해 기술을 발견할 수 있으며, 작업이 일치할 때 상세 지침을 로드할 수 있습니다.

이를 통해 기술은 네 가지 유용한 속성을 갖게 됩니다:

• 발견 가능성(Discoverability): 에이전트가 관련 작업에 대해 기술을 선택할 수 있습니다.
• 범위(Scope): 워크플로가 모든 프롬프트 대신 특정 단계나 기능에 부착됩니다.
• 증거(Evidence): 기술이 테스트, 아티팩트(artifacts), 또는 검토 결과물을 요구할 수 있습니다.
• 버전 관리(Versioning): 워크플로를 코드처럼 검토하고 변경할 수 있습니다.

마지막 속성은 팀들이 자주 놓치는 부분입니다. 일단 기술이 코드나 도구 사용에 영향을 미칠 수 있게 되면, 그 변경 사항은 차이(diff), 소유자(owner), 그리고 롤백 경로(rollback path)를 가져야 마땅합니다.

브라운필드(Brownfield)의 함정: 알 수 없는 동작 위에 라이프사이클을 설치하지 마세요

그린필드(Greenfield) 프로젝트의 경우, 전체 라이프사이클을 도입하는 것이 합리적일 수 있습니다:

/spec -> /plan -> /build -> /test -> /review -> /ship

이미 구축된 리포지토리(Repository)는 다릅니다. 여기에는 문서화되지 않은 계약(contracts), 불균형한 테스트, 그리고 잘못되어 보이지만 시스템을 지탱하고 있는(load-bearing) 동작들이 존재합니다. 즉시 "더 나은 빌드" 워크플로를 적용하면, 에이전트가 아무도 특성화(characterize)하지 않은 코드를 자신 있게 리팩터링(refactor)해버릴 수 있습니다.

대신 읽기 및 보호(read-and-protect) 단계부터 시작하세요:

1. 실제 프로젝트 컨텍스트(Context)를 작성하세요. 빌드 명령, 테스트 명령, 디렉토리 소유권, 알려진 지뢰(landmines), 그리고 금지된 작업들을 기록하세요.
2. 변경하기 전에 검토하세요. 구현을 자동화할 준비가 되지 않았더라도, 들어오는 변경 사항에 대해 검토 기술(review skill)을 사용하세요.
3. 대상 동작을 특성화(Characterize)하세요. 수정할 영역 주변에 테스트를 추가하세요. 이 테스트들은 시스템이 현재 무엇을 하는지를 문서화하는 것이며, 반드시 그 동작을 승인(endorse)해야 하는 것은 아닙니다.
4. 가드(Guard)와 함께 디버깅하세요. 모든 버그 수정은 재현 테스트(reproduction test)나 회귀 테스트(regression test)를 남겨야 합니다.
5. 작은 커밋(Commit)을 채택하세요. 에이전트가 익숙하지 않은 코드를 변경할 때, 작고 이분법적 탐색(bisectable)이 가능한 커밋은 안전 장치가 됩니다.

이러한 과정을 거친 후에야 비로소 새로운 기능이 전체 spec-plan-build-review 경로를 사용할 수 있어야 합니다.

최소한의 채택 정책

모든 세션에 24개의 기술(skills)을 한꺼번에 로드하며 시작하지 마세요. 이는 컨텍스트(context)를 증가시키고, 라우팅 충돌(routing collisions)을 일으키며, 어떤 지시사항이 결정을 제어했는지 파악하기 어렵게 만듭니다.

다음과 같은 정책을 사용하세요:

이 표는 시작을 위한 정책일 뿐, 벤치마크가 아닙니다. 리포지토리의 리스크와 인도(delivery) 제약 조건에 따라 순서를 결정해야 합니다.

기술(Skill) 자체를 검토 가능하게 만드세요

유용한 SKILL.md는 다섯 가지 질문에 답할 수 있어야 합니다:

1. 이 기술(Skill)은 언제 활성화되어야 하는가?
2. 에이전트가 가장 먼저 검사해야 할 입력값은 무엇인가?
3. 허용되는 행동과 금지되는 행동은 무엇인가?
4. 완료를 증명하는 산출물(Artifact)은 무엇인가?
5. 에이전트가 중단하고 인간의 결정을 요청해야 하는 시점은 언제인가?

예를 들어, 리뷰 기술(Review skill)은 다음과 같은 내용을 포함하는 보고서를 요구할 수 있습니다:

skill: review-change
base_commit: 4f2c1b7
changed_files: 7
...

정확한 스키마(Schema)보다는 의사결정을 추적 가능하게 만드는 것이 더 중요합니다. “에이전트가 변경 사항을 검토했다고 말했다”는 증거가 될 수 없습니다. 베이스 커밋(Base commit), 변경된 파일 세트, 명령어, 결과, 그리고 명시적인 결정이 있어야 다른 사람이나 프로세스가 검사할 수 있는 증거가 됩니다.

보안 경계(Security boundaries)는 여전히 기술 외부에 존재해야 합니다

기술은 안전한 절차를 설명할 수는 있지만, 마크다운(Markdown) 지침 그 자체만으로는 보안 경계가 될 수 없습니다. 설치된 기술을 제3자가 작성한 코드처럼 취급하십시오:

• SKILL.md 전체를 읽으십시오.
• 번들링된 스크립트와 의존성(Dependencies)을 검사하십시오.
• 업데이트를 고정(Pin)하거나 검토하십시오.
• 파일 시스템 및 네트워크 접근을 제한하십시오.
• 파괴적이거나 외부적인 부작용(Side effects)이 발생하기 전에 승인을 요구하십시오.
• 거부된 도구들이 실제로 거부되는지 테스트하십시오.

Agent Skills specification은 파일 형식을 문서화합니다. 이것이 임의의 기술을 신뢰할 수 있게 만들어주는 것은 아니며, 저장소(Repository)의 품질에 대한 주장이 독립적인 보안 감사(Security audit)를 대신할 수도 없습니다.

이 접근 방식이 실패하는 경우

워크플로가 매일 변하고 있거나, 트리거(Trigger)가 모호하거나, 절차가 관찰 가능한 증거를 생성할 수 없는 경우 기술(Skill)은 적합하지 않습니다. 또한 기술 간에 충돌이 발생할 수도 있습니다. 두 개의 메타 기술(Meta-skills)이 모두 동일한 요청을 라우팅하려고 시도하거나 서로 호환되지 않는 테스트 규칙을 강제할 수 있습니다.

특성 테스트(Characterization testing)나 의존성 검토(Dependency review)와 같이 범위가 좁은 하나의 기술부터 시작하십시오. 실제 작업의 작은 세트에 대해 실행해 보십시오. 잘못된 활성화(False activations), 건너뛴 게이트(Skipped gates), 리뷰 시간, 그리고 결과물(Artifacts)의 품질을 기록하십시오. 워크플로가 버전 관리를 할 수 있을 만큼 충분히 안정되었을 때에만 확장하십시오.

얼마나 많은 기술(Skills)이 설치되었는가로 성공을 측정하지 마십시오. 저장소에 검토 불가능한 변경 사항이 줄어들었는지, 실패 증거가 더 명확해졌는지, 그리고 더 안전한 롤백(Rollback) 결정을 내릴 수 있는지로 측정하십시오.

실무 체크리스트 (Practical checklist)

기술 팩(Skill pack)을 도입하기 전에:

• 설치하려는 도구가 아니라, 개발 과정의 문제를 명명하십시오.
• 그린필드(Greenfield) 또는 브라운필드(Brownfield) 배포 방식을 명시적으로 선택하십시오.
• 하나의 워크플로(Workflow)와 하나의 증거 결과물(Evidence artifact)로 시작하십시오.
• 프로젝트 컨텍스트(Context)를 작업 절차와 분리하여 유지하십시오.
• 기술(Skills)과 스크립트(Scripts)를 소스 코드처럼 검토하십시오.
• 부수 효과(Side effects)를 활성화하기 전에 승인 및 중단 조건을 정의하십시오.
• 잘못된 활성화(False activations), 건너뛴 게이트(Skipped gates), 검토 부하(Review load), 그리고 되돌리기(Reversals)를 추적하십시오.
• 업데이트 버전을 관리하고 롤백(Rollback) 경로를 유지하십시오.

에이전트 기술(Agent skills)은 훌륭한 엔지니어링 판단을 반복 가능하고 검사 가능한 프로세스로 전환할 때 가치를 발휘합니다. 반면, 팀이 잘 작성된 지침 파일(Instruction file)을 프로세스가 준수되었다는 증거로 착각할 때 기술은 위험해집니다.

출처 (Sources)

• Agent Skills repository
• Agent Skills specification
• Agent Skills adoption guide

여러분의 코드베이스에서 가장 먼저 검토 가능하게 만들고 싶은 첫 번째 워크플로는 무엇입니까: 요구사항(Requirements), 테스트(Testing), 보안 검토(Security review), 아니면 릴리스(Release)입니까?