AI Sparkup

최신 AI 쉽게 깊게 따라잡기⚡

Agent Skills 팁 – AGENTS.md와 Skills로 팀 AI 개발 워크플로 표준화하기

목차

AI 코딩 도구를 팀원마다 따로 쓰면 결과가 들쭉날쭉해진다. 같은 기능 요청이라도 한 사람은 올바른 디렉터리에 테스트까지 만들고, 다른 사람은 팀 컨벤션과 맞지 않는 보일러플레이트를 받는다. 해결책은 프롬프트를 더 길게 쓰는 것이 아니라 프로젝트 맥락과 반복 작업 절차를 저장소 안에 넣는 것이다.

AGENTS.md와 Skills의 역할 분리

파일담당예시
AGENTS.md프로젝트 수준 맥락폴더 구조, 아키텍처, 기술 스택, 코딩 규칙, 테스트 패턴
Skills작업 수준 절차API 엔드포인트 만들기, feature flag 추가, Terraform 모듈 생성, PR 설명 작성

AGENTS.md는 “이 저장소가 어떤 구조로 돌아가는가”를 알려준다. Skill은 “이 작업은 어떤 순서로 해야 하는가”를 알려준다. 둘 중 하나만 있으면 부족하다. AGENTS.md만 있으면 절차가 없고, Skill만 있으면 저장소 맥락이 없다.

좋은 AGENTS.md에 들어갈 내용

  • 제품이 무엇이고 누구를 위한 것인지
  • 루트 디렉터리와 주요 하위 폴더 설명
  • 언어, 프레임워크, 런타임 버전
  • import, naming, error handling 규칙
  • 테스트 디렉터리와 AAA 패턴 같은 팀 관습
  • 금지할 행동: 임의 리팩터링, 테스트 생략, secret 출력 등

핵심은 추상적인 “좋은 코드를 작성하라”가 아니라, 현재 저장소에서 바로 적용 가능한 파일 경로와 관례를 적는 것이다.

Skill로 캡슐화할 작업

Skill은 좁고 반복 가능한 작업에 가장 잘 맞는다.

좋은 Skill 후보이유
새 REST 엔드포인트 추가schema, repository, service, router, test 순서가 반복됨
feature flag 도입config, rollout, test, fallback 패턴이 정해져 있음
구조화 로깅 추가correlation id, metric name, log level 규칙이 필요함
기존 route 테스트 보강unit/integration test 위치와 mock 방식이 반복됨
PR 설명 작성팀 리뷰 템플릿을 강제하기 좋음

반대로 “새 마이크로서비스 전체 구축”처럼 범위가 큰 Skill은 실패하기 쉽다. Skill은 한 번에 끝낼 수 있는 작은 절차여야 한다.

운영 원칙

1. 저장소와 함께 버전 관리한다

AGENTS.md와 Skills를 외부 위키에 두면 금방 낡는다. 코드 구조가 바뀌는 PR에서 지침도 함께 바뀌어야 한다.

2. 소유자를 둔다

Skill은 문서가 아니라 실행되는 개발 프로세스다. 소유자가 없으면 오래된 패턴을 계속 생성한다.

3. 검증 계층을 붙인다

AI 보조 개발의 운영 모델은 “AI로 빠르게 만들고 CI로 검증한다”다. 테스트, lint, static analysis, code review가 없으면 AGENTS.md와 Skills는 속도만 높이고 품질 리스크를 키운다.

4. 안티패턴을 피한다

  • 너무 넓은 Skill
  • 환경에 종속된 brittle path
  • 테스트 지시 없는 Skill
  • 백엔드·프론트엔드·인프라를 한 Skill에 섞기
  • 실제 지침은 위키에 있고 저장소에는 요약만 있는 구조

적용 순서

  1. 먼저 AGENTS.md를 만든다.
  2. 팀이 가장 자주 반복하는 작업 1개를 Skill로 만든다.
  3. 실제 AI 도구로 throwaway branch에서 실행해 결과를 본다.
  4. 누락된 경로, 테스트 규칙, naming을 보강한다.
  5. CI와 리뷰를 통과한 결과만 main에 반영한다.

이 흐름은 GitHub Copilot CLI뿐 아니라 Claude Code, Codex, OpenCode 같은 에이전트 하네스에도 그대로 적용할 수 있다.

관련 문서

참고 자료

AI Sparkup 구독하기

최신 게시물 요약과 더 심층적인 정보를 이메일로 받아 보세요! (무료)