【AI 에이전트 시대의 팀 개발 ⑦】 스킬 파일만으로는 부족하다. AI의 편차를 시스템으로 흡수하기

AI 에이전트 (AI Agent)를 팀 개발에서 사용할 때, 자주 등장하는 대책이 있습니다.

그것이 바로 스킬 파일 (Skill file)이나 프로젝트 규칙을 정비하는 것입니다.

예를 들어, 다음과 같은 것들입니다.

• AGENTS.md
• CLAUDE.md
• Kiro의 steering file
• Copilot의 custom instructions
• 프로젝트 고유의 AI 이용 규칙

이것들은 유효합니다.

AI에게 프로젝트의 전제 조건을 전달하기 위해서는 매우 중요합니다.

하지만, 이것만으로 팀 개발의 코드를 통일하려고 하는 것은 위험하다고 생각합니다.

스킬 파일은 필요합니다.

다만, 그것은 강제가 아니라 유도에 가깝습니다.

스킬 파일에는 예를 들어 다음과 같은 내용을 적습니다.

- Controller는 가볍게 유지할 것
- Service에 비즈니스 로직 (Business Logic)을 작성할 것
- DTO의 명명은 XxxRequest / XxxResponse로 할 것
...

이것은 유효합니다.

AI가 프로젝트의 방침을 이해하기 쉬워집니다.

매번 같은 설명을 하지 않아도 됩니다.

팀 전체에서 AI에 대한 전제 조건을 맞추기 쉬워집니다.

하지만, AI가 반드시 지킨다는 보장은 없습니다.

AI는 컴파일러 (Compiler)가 아닙니다.

규칙을 적었다고 해서 반드시 따르는 것은 아닙니다.

컨텍스트 (Context) 양, 최근의 지시, 읽게 한 파일, 모델의 동작, 작업 내용에 따라 규칙에서 벗어날 수 있습니다.

따라서 스킬 파일에만 의존하는 것은 위험합니다.

스킬 파일을 충실하게 만들려고 하면 점점 길어지기 쉽습니다.

• 명명 규칙 (Naming Convention)
• 디렉토리 구성 (Directory Structure)
• 예외 처리 (Exception Handling)
• 로그 출력 (Log Output)
• 테스트 방침 (Test Policy)
• 금지 사항
• 리뷰 관점
• UI 규칙
• API 규칙

이것들을 전부 적고 싶어집니다.

하지만 너무 긴 규칙은 AI에게도 다루기 어려워집니다.

모든 것을 매번 완벽하게 지키는 것은 기대하기 어렵습니다.

따라서 문장으로 쓰는 규칙과 기계적으로 제약하는 규칙을 나눌 필요가 있습니다.

스킬 파일에 적합한 것은 판단 기준이나 설계 사상입니다.

예를 들어, 다음과 같은 것입니다.

• 이 프로젝트에서 중요하게 여기는 설계 방침
• 책임 분담 (Responsibility Segregation)에 대한 생각
• 기존 코드를 우선하는 방침
• 리팩토링 (Refactoring)을 섞지 않는 방침
• 망설여질 때의 판단 기준
• AI가 작업 전에 확인해주길 바라는 것

즉, 인간이라도 기계라도 완벽하게 판정하기는 어렵지만, 방향성으로서 중요한 것들입니다.

이런 것들은 문장으로 AI에게 전달할 가치가 있습니다.

반면, 기계적으로 확인할 수 있는 것은 문장이 아니라 도구 (Tool)로 제약해야 합니다.

예를 들어 다음과 같습니다.

• formatter
• lint
• 타입 체크 (Type Check)
• 단위 테스트 (Unit Test)
• 결합 테스트 (Integration Test)
• CI (Continuous Integration)
• 의존 방향 체크 (Dependency Direction Check)
• 금지된 import 체크
• 커버리지 (Coverage) 확인
• 빌드 (Build) 확인

이것들은 AI에게 "지켜주세요"라고 부탁하는 것보다, CI에서 탈락시키는 것이 확실합니다.

AI가 아무리 "수정을 완료했습니다"라고 말해도, 테스트가 실패하면 머지 (Merge)할 수 없습니다.

lint를 위반하고 있다면 머지할 수 없습니다.

금지된 의존 방향이 있다면 머지할 수 없습니다.

이런 상태를 만드는 것이 중요합니다.

코드의 형태를 맞추고 싶을 경우, 문장으로 설명하는 것만으로는 불충분합니다.

그 경우에는 템플릿이나 히나타 (Template)를 준비하는 것이 효과적입니다.

예를 들어 프론트엔드 (Front-end)라면 다음과 같은 것입니다.

• 페이지 컴포넌트의 템플릿
• 검색 폼의 템플릿
• API 호출 hooks의 템플릿
• 테스트 파일의 템플릿

백엔드 (Back-end)라면 다음과 같습니다.

• Controller의 템플릿
• Service의 템플릿
• Repository의 템플릿
• Request / Response DTO의 템플릿
• 테스트 코드의 템플릿

AI에게 "이 방침으로 작성해줘"라고 전달하는 것보다, 처음부터 형태를 전달하는 것이 통일하기 쉽습니다.

AI에게는 그 템플릿을 바탕으로 필요한 부분을 채우게 합니다.

이를 통해 AI의 자유도를 적절히 제한할 수 있습니다.

AI의 출력을 완전히 고정하는 것은 어렵다고 생각합니다.

또한, 반드시 고정해야 하는 것도 아닙니다.

AI는 새로운 해결책을 제시해 줄 때가 있습니다.

기존 구현보다 더 나은 제안을 해줄 때도 있습니다.

그 편차(ブレ) 자체는 AI의 강점이기도 합니다.

중요한 것은 편차를 완전히 없애는 것이 아닙니다.

편차가 생기더라도 팀 개발이 무너지지 않도록 하는 것입니다.

그러기 위해서는 다음과 같은 메커니즘이 필요합니다.

• 스킬 파일 (Skill file)로 방향 설정하기
• 대표 구현 (Reference implementation) 준비하기
• 템플릿 (Template)으로 형태 고정하기
• lint / test / CI로 일탈 감지하기
• PR (Pull Request)을 작게 유지하기
• 차이점 리뷰 (Diff review) 수행하기

이러한 조합이 현실적입니다.

스킬 파일은 유효합니다.

하지만, 그것만으로 AI의 출력을 통일하려고 하는 것은 위험합니다.

스킬 파일은 AI에 대한 강제가 아니라, 유도에 가깝습니다.

정말로 맞추고 싶은 것은 문장뿐만 아니라, 기계적으로 확인할 수 있는 메커니즘으로 구현할 필요가 있습니다.

• formatter
• lint
• 타입 체크 (Type check)
• 테스트 (Test)
• CI (Continuous Integration)
• 템플릿 (Template)
• 템플릿 (Template)
• PR 템플릿 (PR template)

AI에게 똑같은 코드를 쓰게 하는 것보다, AI가 다소 흔들리더라도 동일한 품질로 수렴하는 메커니즘을 만드는 것이 중요합니다.

다음 회차에서는 AI 시대에 베테랑 엔지니어의 역할이 어떻게 변하는지 생각해보겠습니다.

이후 연재 예정 목록입니다.

• 제1회: 같은 AI를 사용하고 있는데, 왜 코드가 제각각인가
• 제2회: AI가 작성한 '동작하는 코드'가 팀 개발에서는 위험한 이유
• 제3회: AI에게 맡겼더니 컨플릭트(Conflict)투성이가 된 이야기
• 제4회: AI에게 '이 파일 외에는 건드리지 마'라고 말하는 것이 옳은가
• 제5회: AI 시대의 PR은 왜 무거워지기 쉬운가
• 제6회: AI에게는 세세하게 지시하지 않는 편이 좋다,는 팀 개발에서도 통하는가
• 제7회: 스킬 파일만으로는 부족하다. AI의 편차를 시스템으로 흡수하기
• 제8회: AI 시대의 베테랑은 코드를 쓰는 사람에서 메커니즘을 만드는 사람으로