AI네부캠

프로젝트의 AI 활용 컨벤션을 정립하고, 테스트 작성에 활용해보기

2026년 3월 31일

팀의 AI 활용 컨벤션을 만들어보자

team.config 프로젝트를 어느정도 마무리 짓고 나니, AI를 팀 단위로 잘 쓸 수 있는 방법은 없을까 하는 생각이 들었다. 우리 프로젝트의 주제가 “개발 팀의 컨벤션 정립을 도와주는 서비스”이다 보니, “AI 활용도 이제 팀 컨벤션이 필요하지 않나?”하는 생각이 문득 스친것 같다.

개인적으로는 팀 컨벤션을 지키면서, 문제 해결 과정이 잘 드러나는 커밋 메시지를 빠르게 쓰고 싶어.cursorrules를 만들어 커밋 작성 방법에 대한 설명을 기술해 두었다.

.cursorrules 은 커서 IDE를 통해 ai 기능을 사용할 때, 자동으로 주입되는 컨텍스트이다. 커밋 메세지 컨벤션에 대한 규칙을 AI한테 알려주니까 커밋 작성이 확실히 편해졌다.

하지만, 해당 설정을 팀 단위로 공유하지는 못했다. 이유는 크게 아래와 같다.

일단 .cursorrules은 커서라는 IDE에 종속되어 있는 파일로, 모든 팀원이 커서를 쓰는게 아니기에, 이 파일을 git으로 관리하거나 공유하는건 적절하지 않다고 생각했다.
팀에서는 각자 자유롭게 AI를 쓰고 있었고, 딱히 "AI를 이렇게 쓰자"는 합의가 없었다.

그러다 보니 좋은 프롬프트를 발견해도 나만 쓰고, AI가 반복하는 실수에 대해 프롬프트를 반복해서 작성하게 되고, 공유되지 않는다는 게 아쉬웠던 것 같다.

각자의 노하우가 팀 전체에 자연스럽게 쌓이면 좋겠다는 생각이 들었고, 이에 claude.md를 팀 단위로 도입해보기로 했다.

모노레포에서의 `claude.md`

web15-ipconfig/
 ├── backend/     ← NestJS
 ├── frontend/    ← React + Vite
 ├── docs/
 ├── nginx/
 └── docker-compose*.yml

우리 프로젝트 team.config의 구조는 크게 프론트엔드와 백엔드가 함께 있는 모노레포로 되어 있다. Claude Code에서 /init을 치면 claude.md 초안을 쉽게 만들 수 있다. 하지만, 프론트엔드와 백엔드가 함께 있는 모노레포에서는 하나의 claude.md 전부 프로젝트 내용을 담기에는 문제가 있다.

첫째, 분량 제한이다. claude.md는 200줄을 넘으면 AI가 내용을 제대로 파악하지 못하고 무시할 수 있다. 모노레포의 양쪽 컨벤션을 전부 넣기엔 빠듯했다.

둘째, 컨텍스트 낭비. claude.md는 세션을 시작할 때마다 전체 내용이 올라간다. 프론트엔드만 작업하는데 백엔드 컨벤션까지 같이 올라가면, 토큰이 낭비되는 것도 문제지만, AI가 지금 뭘 더 중요하게 봐야 하는지 흐려질 수 있다.

claude에서는 하위 claude.md를 지원한다. 이 경우 claude에 해당 디렉토리에 접근할 때만 해당 claude.md 내용을 context에 올린다. 따라서 조금 더 토큰을 절약하면서도, 컨텍스트를 잘 관리할 수 있다.

우리팀의 컨벤션을 반영해보자

우리 팀에는 이미 코드 컨벤션 문서가 있었다. 다만 프론트엔드와 백엔드 내용이 한 문서에 섞여 있었다.

이걸 정리해서 frontend/claude.md와 backend/claude.md로 분리했다. 각 패키지 디렉토리에 해당 영역의 컨벤션만 담긴 claude.md를 두니, 프론트엔드 작업할 때는 프론트엔드 컨텍스트만, 백엔드 작업할 때는 백엔드 컨텍스트만 올라가게 됐다.

커밋해보기

claude가 claude.md를 잘 파악하고 커밋 컨벤션대로 커밋 메세지가 잘 작성되는지 확인하기 위해 claude로 커밋을 해보았다.

💡

<type>: <내용>으로 기재하며, 상세 내용은 불렛포인트로 작성한다.

이미지를 보면 컨벤션에 맞게 잘 생성된 것을 확인할 수 있다. 이로써, AI에게 우리 프로젝트를 설명하는 전반적인 컨텍스트를 생성할 수 있었다.

해당 작업에 대한 내용은 아래 PR에서 확인할 수 있다.

docs: AI 컨텍스트용 CLAUDE.md 추가 (루트/프론트엔드/백엔드)

Pull Request #399 · Grit03 · boostcampwm2025/web15-ipconfig

AI를 활용하여 테스트에 대한 기술 부채 해결하기

프로젝트 기간동안 기능 구현에 집중했기 때문에, 프론트엔드에 대한 테스트 코드가 매우 미흡했다. 하지만 이미 구현한 기능이 많기 때문에, 전부 테스트를 작성하기도 쉽지 않았다.

또한 테스트 작성 경험이 많지 않은 상태에서, 컨벤션을 잘 맞추고, 좋은 테스트 코드를 작성하기 어려운 상황이라 생각이 되었다. 이러한 상황에서 공식 문서 기반으로 스킬을 만들고 테스트코드를 빠르게 병렬로 생성해줄 에이전트를 만든다면, 빠르게 테스트를 작성하여, 기술 부채를 해결할 수 있을 것이라 생각했다.

테스트 코드 작성을 위한 `Skill` 생성하기

💡

Skill은 Claude가 특정 작업을 더 잘 수행할 수 있도록 도와주는 전문 지침 파일(SKILL.md)이다. 한번에 컨텍스트를 불러오는 것이 아닌, 점진적으로 필요할 때, 컨텍스트를 불러온다는 장점이 있다.

vitest의 공식문서와 최근에 감명깊게 읽었던 “단위 테스트의 기술”이라는 책의 내용에서 인상 깊었던 부분을 Skill에 사용할 reference로 만들면 좋겠다고 생각했다. 리서치해본 결과 책의 저자가 작성한 블로그 글을 찾을 수 있고, 해당 내용과 AI를 활용하여 리서치한 내용을 바탕으로 AI 요약본을 구성했다. 그리고 vitest에서도 중요한 공식문서 내용을 AI를 활용하여 요약했다.

해당 내용을 바탕으로 클로드의 자체 스킬인 /skill-creator 를 활용해서 스킬을 만들었다. 스킬의 이름은 frontend-test라고 작성했다.

.claude/
	└── skills/
	    └── frontend-test/
	        ├── SKILL.md                    # 스킬 진입점 (판단 흐름·원칙·명령어)
	        └── reference/                  # 스킬이 참조하는 지식 문서
	            ├── testing-principle.md    # 테스트 철학 (Roy Osherove 원칙)
	            ├── component-testing.md    # RTL 컴포넌트 테스트 패턴
	            ├── mocking.md              # Vitest 공식 문서 기반 모킹 전략
	            ├── setup.md                # Vitest 설정 및 실행 명령어
	            └── snapshot.md             # 스냅샷 테스트 사용 기준

위의 구조대로 reference를 활용해서 Skill이 잘 만들어진 것을 확인할 수 있었다.

테스트 코드를 작성할 에이전트 생성

테스트는 보통 특정 기능, 컴포넌트 단위 별로 만든다. 물론 통합 테스트도 있지만, 지금은 테스트가 없는 상황에서 중요한 컴포넌트 혹은 로직을 검증하기 위한 단위 테스트를 만드는 것에 가깝다고 생각이 든다.

그런 관점에서 각 기능, 컴포넌트 별로 테스트를 만들 수 있으므로, 서브 에이전트를 활용해 병렬로 빠르게 만들 수 있을 것이라고 생각이 들었다. 병렬로 빠르게 서브에이전트로 여러 개의 테스트를 동시에 추가하면, 빠르게 테스트를 작성해 부족한 부분을 채울 수 있을 것이라 생각했다.

테스트를 위한 서브 에이전트를 frontend-tester 로 이름짓고, 해당 에이전트가frontend-tester 스킬을 활용하여 테스트 코드 작성을 할 수 있도록 설정했다.

특정 에이전트가 사용할 스킬은 frontmatter의 skills 필드로 스킬을 작성하여 지정할 수 있다.

---             
name: frontend-tester
description: >  
team.config 프론트엔드 테스트 전문 에이전트. 컴포넌트, 커스텀 훅, Yjs CRDT 로직, 
유틸 함수에 대한 테스트를 작성하고 실행한다. 
skills:
  -  frontend-test     # ← 이 줄이 스킬을 에이전트에 주입 
tools: Read, Grep, Glob, Bash, Edit, Write                                     
model: sonnet   
---

에이전트는 .claude/agents 하위에 생성할 수 있다. 원하는 에이전트 이름을 디렉토리명으로 하고, 에이전트에 대한 설명을 AGENT.md 에 기술해주면 된다.

.claude/                               
  ├── skills/
  │   └── frontend-test/       ← 기존 스킬 (이미 존재) 
  │       ├── SKILL.md  
  │       └── reference/         
  └── agents/ 
      └── frontend-tester/     ← 새로 생성
          └── AGENT.md

테스트 스킬을 사용하는 서브 에이전트로 테스트 작성

이제 만든 스킬과 이를 사용하는 에이전트를 서브 에이전트로 만들어 빠르게 테스트를 생성해보자!

직접 스킬을 커맨드로 지시하거나, 병렬로 에이전트롤 생성하여 테스트를 작성하고 싶다고 하면, 해당 스킬 혹은 에이전트를 활용하여 테스트를 작성할 수 있다. 위 이미지는 후자의 방식으로 프롬프트를 작성한 것이다.

메인 agent는 병렬로 요청한 일을 처리할 수 있을 만큼의 subagent를 생성하고, 해당 subagent는 사용가능한 스킬을 활용하여 작업을 진행한다. 진행한 작업이 완료되면 요약되어 메인 agent한테 전달되고 해당 subagent는 사라진다.

💡

서브에이전트는 결과물만 돌려주고, 자신이 작업하면서 쌓은 긴 컨텍스트(중간 과정, 시행착오 등)는 버려진다.

결과

AI를 활용하여 테스트 코드 작성은 아래와 같이 테스트 케이스가 작성되었다.

CounterInput 컴포넌트 테스트 (9개)
PRRules 컴포넌트 테스트 (6개)

2분 37초만에 두 컴포넌트에 대한 테스트를 작성할 수 있었다.

작성된 테스트 코드를 실행시켜보니, 정상적으로 컴포넌트 테스트가 실행되고, 현재 구현된 로직으로 테스트가 통과되는 것을 확인할 수 있었다.

작성된 스킬과 서브 에이전트에 대한 내용, 구현된 테스트는 아래 PR에서 확인할 수 있다.

test(frontend): 테스트 작성을 도울 Skill 및 Subagent 구축하여 컴포넌트 테스트 추가

Pull Request #400 · Grit03 · boostcampwm2025/web15-ipconfig

정리하며

팀 단위로 AI 활용을 어떻게 잘 할 수 있을까 고민하며, claude.md를 추가하고, 테스트 작성에 Skill과 agent를 활용해보았다.

claude.md, subagent, agents teams, mcp 등의 용어를 학습하며, 컨텍스트 엔지니어링이 무엇인지 조금씩 알아가고 있었는데, 실제 프로젝트에 이를 활용하여 적용해보니까 재미있었던 것 같다. 컨텍스트 엔지니어링에 대해서 더 깊게 학습해보고 싶다는 생각이 들었다.

실제로 운영을 계속해나가면서, 팀만의 스킬과 에이전트 활용 방법으로 쌓아나갈 수 있다면, AI 활용에 대한 감을 더 잡을 수 있지 않을까 생각이 든다.