코딩 Skill을 처음 떠올리면 많은 사람이 이렇게 생각한다. "AI가 코드를 더 잘 짜게 만드는 비법인가?" 하지만 실무에서는 질문을 바꿔야 한다. 코딩 Skill의 본질은 모델의 코딩 실력을 키우는 것이 아니라, 팀의 개발 방식을 흔들리지 않게 강제하는 데 있다.
같은 모델이라도 어떤 저장소에서는 깔끔하게 일하고, 어떤 저장소에서는 제멋대로 굴어 보이는 이유가 여기에 있다. 모델의 지능 차이보다 더 큰 차이는, 그 프로젝트가 에이전트에게 무엇을 항상 지키게 했는지에 달려 있다. 잘 만든 코딩 Skill은 시니어 개발자의 머릿속에 있던 개발 절차, 품질 게이트, 리뷰 기준을 에이전트가 반복해서 따르게 만드는 장치다.1
코딩 Skill은 "코드 작성법"보다 "팀의 방식"을 담아야 한다
코딩 업무는 얼핏 보면 모두 비슷해 보인다. 기능을 추가하고, 버그를 고치고, 테스트를 돌리고, PR을 올리면 끝난다. 하지만 실제로는 프로젝트마다 전혀 다르다. 어떤 팀은 API 입력 검증을 도메인 계층에서만 하게 하고, 어떤 팀은 프론트엔드 상태 관리를 특정 훅 패턴으로만 통일한다. 어떤 팀은 모든 변경 전에 ADR을 남기고, 어떤 팀은 100줄이 넘는 변경이면 반드시 쪼개서 올리게 한다.
바로 이 차이가 Skill에 들어가야 한다. 에이전트는 언어 문법보다 로컬 관례에서 더 자주 실패한다. 함수 하나는 그럴듯하게 써도, 파일을 엉뚱한 폴더에 만들고, 테스트 위치를 틀리고, 기존 예외 처리 패턴을 깨뜨리면 팀 입장에서는 좋은 코드가 아니다.
그래서 코딩 Skill은 먼저 이 질문에 답해야 한다.
이 저장소에서 코드는 어디에 놓이는가
무엇을 수정해도 되고, 무엇은 건드리면 안 되는가
어떤 명령으로 빌드, 테스트, 타입체크, 린트를 검증하는가
어떤 예제가 이 프로젝트의 정답에 가장 가까운가
이런 정보는 모든 대화에 늘 붙는 정적 규칙과, 특정 코딩 업무에서만 불러오는 Skill로 나눠 담는 편이 좋다. Cursor의 가이드도 규칙은 짧은 상시 컨텍스트로, Skills는 필요할 때 로드되는 동적 워크플로우로 다루라고 권한다.2 다시 말해, "이 프로젝트는 어떤 법을 지키는가"는 규칙에 두고, "이번 작업은 어떤 절차로 처리할 것인가"는 Skill에 두는 것이다.
프로젝트 규칙과 디렉터리 관례는 참조 중심으로 적어라
코딩 Skill을 만들 때 흔히 저지르는 실수가 하나 있다. 팀의 스타일 가이드 전체를 SKILL.md에 복사해 넣는 것이다. 이 방법은 금방 낡고, 길고, 읽기 힘들어진다. 더 좋은 방식은 대표 파일을 기준점으로 삼는 것이다.
예를 들어 이렇게 적는 편이 낫다.
React 페이지는
app/아래 기존 라우트 구조를 따른다API 핸들러는
app/api/의 기존 패턴을 복제해 확장한다비즈니스 로직은
src/domain/에 두고, UI 컴포넌트에서 직접 구현하지 않는다대표 예시는
src/features/auth/와components/Button.tsx를 먼저 읽는다
이렇게 하면 Skill이 규칙을 장황하게 설명하는 대신, 에이전트가 정답에 가까운 파일을 먼저 읽게 만든다. AGENTS.md 역시 바로 이런 목적의 문서다. 사람용 README와 별도로, 빌드 명령, 테스트 방법, 코드 스타일, PR 규약처럼 에이전트가 작업 전에 알아야 할 내용을 예측 가능한 위치에 둔다. 모노레포에서는 더 가까운 위치의 AGENTS.md가 우선하므로, 패키지별로 관례가 다른 경우 특히 유용하다.3
실무 감각으로 정리하면 이렇다. 규칙은 원칙을 적고, Skill은 그 원칙을 실제 작업 순서로 연결한다.
테스트 우선은 문장이 아니라 절차여야 한다
"테스트도 같이 작성해 줘"는 코딩 Skill이 아니다. 좋은 의도일 뿐이다. 코딩 Skill이 되려면, 테스트를 반드시 먼저 거치게 만드는 순서가 있어야 한다.
에이전트는 기본적으로 구현으로 달려가려는 성향이 있다. 빈칸을 보면 채우고 싶어 하고, 오류를 보면 코드를 바로 고치고 싶어 한다. 그래서 테스트 우선 문화를 지키고 싶다면, Skill 안에서 순서를 잠가야 한다. 예를 들어 다음처럼 말이다.12
변경 범위를 요약한다.
기존 테스트와 관련 파일을 찾는다.
새 동작 또는 버그 재현용 테스트를 먼저 작성한다.
그 테스트가 기대한 이유로 실패하는지 확인한다.
최소 구현으로 테스트를 통과시킨다.
관련 타입체크, 린트, 대상 테스트를 다시 돌린다.
필요하면 리팩터링하되 테스트 의미는 바꾸지 않는다.
이 절차의 핵심은 "테스트는 증거"라는 태도다. 테스트가 없으면 에이전트는 자꾸 "이제 된 것 같습니다"라고 말한다. 그러나 실무에서 필요한 것은 느낌이 아니라 증명이다.1
특히 버그 수정 Skill에서는 이 순서가 더 중요하다. 재현 테스트 없이 바로 고치면, 에이전트는 증상을 없앤 줄 알았는데 다른 경로를 망가뜨릴 수 있다. 테스트 우선은 느려 보이지만, 실제로는 재작업을 줄여서 더 빠르게 만든다.
PR 규약과 리뷰 톤은 출력 포맷으로 고정해야 한다
코딩 Skill의 또 다른 핵심은 리뷰다. 많은 팀이 여기서 손해를 본다. 에이전트가 리뷰를 하긴 하는데, 어떤 날은 지나치게 공격적이고, 어떤 날은 칭찬만 하며, 어떤 날은 사소한 취향 문제를 치명적 이슈처럼 말한다.
이 흔들림을 줄이는 가장 좋은 방법은 리뷰 결과를 포맷화하는 것이다. 예를 들어 리뷰 결과를 항상 다음 순서로 출력하게 할 수 있다.
변경 요약: 이 PR이 무엇을 바꾸는지 2~3문장으로 요약
위험도: low, medium, high
핵심 발견 사항: 파일, 위치, 문제 설명, 권장 수정
검증 상태: 테스트, 린트, 타입체크 실행 여부
머지 판단: 바로 머지 가능 / 수정 후 재검토 / 블로킹 이슈 존재
여기에 심각도 레이블까지 붙이면 훨씬 좋아진다. 실제 코드 리뷰 Skill 사례를 보면 blocking, important, nit, suggestion, learning, praise처럼 발견 사항의 무게를 구분하고, 명령형보다 질문형에 가까운 협업 톤을 유지하도록 설계한다.4 이 방식의 장점은 단순하다. 리뷰가 더 공정해지고, 저자가 무엇부터 고쳐야 하는지 명확해진다.
특히 팀 리더라면 리뷰 Skill에 다음 규칙을 꼭 넣는 것이 좋다.
린터가 잡을 문제는 리뷰에서 장황하게 반복하지 않는다
취향 문제와 유지보수 위험을 구분한다
칭찬할 점도 한 줄 이상 남긴다
수정 제안은 가능하면 이유와 함께 적는다
이 네 줄만 있어도 리뷰는 훨씬 사람다워진다. 차갑지 않으면서도, 흐리지 않다.
마이그레이션 Skill은 "한 번에 바꾸기"를 막아야 한다
마이그레이션 작업은 AI 에이전트가 겉보기에는 잘하는 것처럼 보이지만, 실제로는 사고가 자주 나는 영역이다. 이유는 간단하다. 마이그레이션은 새 코드를 쓰는 작업이 아니라, 기존 시스템을 안전하게 바꾸는 작업이기 때문이다.
그래서 마이그레이션 Skill에는 멋진 구현보다 체크리스트가 더 중요하다. 보통 다음 순서로 고정하는 편이 좋다.1
현재 구조와 새 구조를 비교해 변경 범위를 목록화한다.
호환 기간이 필요한지 판단한다.
데이터 변환이나 API 계약 변경 여부를 명시한다.
롤백 방법을 먼저 적는다.
가능하면 작은 단위로 나눠 순차 적용한다.
검증 명령과 관찰 포인트를 정한다.
전환 후 제거해야 할 임시 코드와 좀비 코드를 기록한다.
이때 Skill이 꼭 막아야 하는 것이 있다. 한 번의 거대한 리팩터링으로 모든 것을 끝내려는 유혹이다. 에이전트는 종종 자신감 있게 큰 변경을 제안한다. 하지만 운영 환경에서는 작은 조각, 기능 플래그, 롤백 가능한 커밋이 더 안전하다. 코딩 Skill은 바로 그 안전한 겁쟁이 역할을 해야 한다.
버그 재현 Skill은 진단보다 먼저 "재현 가능성"을 만든다
사람도 그렇지만 에이전트도 버그를 보면 곧장 원인을 추측하고 싶어 한다. 그러나 좋은 디버깅은 추측에서 시작하지 않는다. 재현 가능한 실패에서 시작한다.
버그 재현 Skill은 문제를 이렇게 다루게 해야 한다.15
환경과 버전을 확인한다.
최소 재현 경로를 만든다.
기대 결과와 실제 결과를 분리해 적는다.
로그, 스크린샷, 네트워크 기록 같은 증거를 수집한다.
가능한 한 작은 재현 테스트나 스크립트를 만든다.
그 다음에야 원인 분석과 수정에 들어간다.
이 순서가 중요한 이유는, 재현과 진단을 섞는 순간 모든 것이 흐려지기 때문이다. "아마 이 함수가 문제일 것 같다"는 말은 빠르지만 위험하다. 반면 "이 입력을 넣고, 이 페이지에서, 이 버튼을 누르면, 이 로그와 함께 실패한다"는 말은 느려 보여도 훨씬 강하다.
특히 주니어 개발자나 비개발 직군과 함께 일하는 팀일수록 버그 재현 Skill의 가치가 크다. 문제를 잘 설명하는 사람은 드물지만, 좋은 Skill은 재현 설명 자체를 표준화할 수 있기 때문이다. 버그를 고치는 능력보다 버그를 같은 방식으로 다시 만들 수 있는 능력이 먼저다.
Claude Code, Cursor, Codex에서 공통으로 먹히는 설계 포인트
도구마다 UI는 다르지만, 잘 만든 코딩 Skill의 핵심은 놀랄 만큼 비슷하다. 이유는 간단하다. 많은 코딩 에이전트가 결국 Markdown 기반 지침, 검색 도구, 파일 편집, 셸 실행, 검증 루프를 중심으로 움직이기 때문이다.1
공통으로 잘 먹히는 포인트는 다음과 같다.
계획부터 시작하게 만들기: 바로 코드를 쓰게 하지 말고, 변경 파일과 검증 방법이 포함된 짧은 계획을 먼저 세우게 한다.2
대표 예시를 먼저 읽게 만들기: 전체 코드베이스를 설명하기보다, "이 파일을 기준으로 따라라"가 더 강력하다.
검증 명령을 명시하기:
pnpm test,pnpm typecheck,pnpm lint처럼 실제 명령을 정확히 적는다.출력 포맷을 고정하기: 리뷰, PR 요약, 버그 리포트가 매번 같은 틀을 갖게 한다.
도구 우선 원칙을 분명히 하기: 파일 읽기, 편집, 린트 확인처럼 안전한 전용 도구가 있으면 셸보다 그것을 우선 쓰게 한다.6
여기서 특히 중요한 것은 마지막 항목이다. Codex 계열 모델은 셸 중심 워크플로우에 익숙한 편이라, 그냥 두면 cat, grep, 인라인 스크립트 작성으로 흘러갈 수 있다. Cursor는 이런 모델들을 더 안전하게 쓰기 위해 "도구가 있으면 도구를 우선 사용하라", "실질적 수정 뒤에는 린트 오류를 읽고 고쳐라" 같은 하니스 지침을 추가했다고 밝힌 바 있다.6 이 차이를 이해하면 Skill도 더 좋아진다. 특정 에디터 기능에 의존하기보다, 읽기-수정-검증의 안전한 기본 흐름을 적어 두는 것이 좋다.
코딩 Skill의 작은 예시
아래는 프로젝트용 코딩 Skill이 어떤 느낌이어야 하는지 보여 주는 짧은 예시다.
---
name: feature-implementation
description: Implement features in this repository using test-first workflow, existing directory conventions, and mandatory verification.
---
## Before editing
1. Read the nearest AGENTS.md and project rules.
2. Inspect canonical examples in `src/features/auth/` and `app/api/`.
3. Summarize the plan with target files and verification commands.
## Workflow
1. Write or update a failing test first.
2. Confirm the test fails for the expected reason.
3. Implement the smallest change that makes the test pass.
4. Run typecheck, lint, and affected tests.
5. If the change exceeds a small reviewable size, propose splitting it.
## Output
- What changed
- Why it changed
- Verification run
- Risks or follow-up work이 예시는 화려하지 않다. 하지만 실무에서는 이런 Skill이 강하다. 왜냐하면 에이전트가 "대충 그럴듯한 코드"가 아니라 "우리 팀이 머지할 수 있는 코드"를 향해 움직이기 때문이다.
좋은 코딩 Skill은 에이전트를 자유롭게 하지 않고, 안전하게 만든다
코딩 Skill의 목표는 에이전트에게 더 많은 자유를 주는 것이 아니다. 오히려 반대다. 함부로 건드리지 못하게 하고, 아무렇게나 리뷰하지 못하게 하고, 테스트 없이 끝냈다고 말하지 못하게 만드는 것이다.
바로 이 제약이 품질을 만든다. 개발 조직에서 반복되는 실수는 대개 능력 부족보다 절차 부재에서 생긴다. 파일은 잘 만들었지만 위치가 틀렸고, 기능은 돌아가지만 테스트가 없고, 리뷰는 했지만 기준이 없고, 마이그레이션은 됐지만 롤백이 없다. 코딩 Skill은 이 빈칸을 메운다.
결국 잘 만든 코딩 Skill은 이렇게 말하는 시스템이다.
"코드는 써도 된다. 하지만 우리 방식대로 써야 한다."
이 한 문장이야말로, AI를 코더가 아니라 팀의 개발 프로세스를 따르는 실행자로 바꾸는 출발점이다.
참고
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.