[AI] 일관성이 보장된 AI 개발 환경 구축하기

시리즈 목차: 역할별 AI 페르소나 하네스 구축기

1편: [AI] 일관성이 보장된 AI 개발 환경 구축하기 (읽고있는 글)

2편: [AI] 지속가능한 AI 개발 환경 구축하기

 

프롤로그

 최근 저는 혼자서 AI를 적극적으로 활용하여 디자인 시스템을 제작하고 있습니다.

 단순히 코드 몇 줄을 짜주는 '도구'를 넘어, 프로젝트의 원칙을 함께 지키며 일하는 '가상의 팀원'으로 AI를 정의해 보고 있습니다. 이를 통해 일관성 있는 AI 개발 환경을 구축하고, 'AI 네이티브(AI-Native) 개발'을 실험하는 중입니다.

 가장 먼저 시작한 일은 AI에게 명확한 역할(페르소나)을 부여하는 것이었습니다.

• 개발 담당 (Developer)
• 코드 리뷰 담당 (Challenger)
• 문서화 담당 (Documenter)
• 회고 담당 (Retrospective)
• UX 라이팅 담당 (Writer)

 하지만 이렇게 각각의 역할을 문서로 정리해두는 것만으로는 AI가 항상 일관성 있게 행동해주지 않았습니다. 대화를 시작할 때마다 "이번에는 개발 페르소나를 적용해줘"라고 명시적으로 지정해주지 않으면, AI가 자신이 어떤 역할인지 잊거나 페르소나 자체가 적용되지 않는 문제가 발생했기 때문입니다.

이를 해결하기 위해, 저는 AI가 스스로 역할을 찾아가도록 만드는 "역할별 AI 페르소나 라우터 구축"에 돌입하게 되었습니다.

 

---

문제 원인 - 왜 AI는 자꾸 역할을 까먹을까?

 제가 앞서 공들여 작성해 둔 'AI 역할 문서'들은 한 곳에 잘 정리되어있지만, AI 도구들이 이 문서들을 알아서 찾아 읽지 못한다는 것이 문제의 핵심이었습니다.

 대부분의 AI 코딩 도구(Claude, Gemini, Cursor 등)는 약속된 특정 폴더나 특정 이름의 파일만 기본 설정값으로 읽어오도록 설계되어 있습니다. 그렇기 때문에 제가 직접 파일을 가리키거나 매번 지시하지 않으면, AI 입장에서는 아무런 규칙도 배정받지 못한 텅 빈 상태로 대답할 수밖에 없었던 것이죠.

 

1. AI 페르소나에 "라우터 패턴" 적용하기

 

"프롬프트를 전달하면, AI가 스스로 맥락을 이해하고, 알맞은 페르소나가 적용되게 할 순 없을까?"

 

 고민 끝에 떠올린 방법은 바로 "라우터(Router) 패턴"이었습니다. 웹사이트에서 사용자가 입력한 주소에 따라 알맞은 화면으로 이동시켜주듯, 프롬프트 내용에 따라 알맞은 역할 문서로 안내해 주는 '길잡이 문서'를 하나 만드는 것입니다.

 설계한 아이디어를 도식화해 보면 다음과 같습니다.

 

 이 아이디어를 실험하기 위해, 현재 제가 사용하는 AI 도구가 자동으로 읽어올 수 있는 공식 위치에 이 '페르소나 라우터'를 작성해 주었습니다. 이 문서 안에는 어떤 질문이 들어왔을 때 어떤 역할(페르소나)을 적용해야 하는지에 대한 판단 기준이 적혀 있습니다.

# 페르소나 라우터
사용자가 입력한 프롬프트의 맥락을 분석해서, 아래 규칙에 따라
가장 적합한 페르소나를 스스로 선택하고 그 지침에 맞춰 응답해주세요.

## 페르소나 선택 규칙
1. 개발 및 구현
  - 새로운 컴포넌트 작성, 기능 구현, 버그 수정, 아키텍처 관련 질문, 기술 스택 적용 등.
  - developer.md를 적용해요.

2. 코드 리뷰 및 피드백
  - 작성한 코드 리뷰 요청, 리팩토링 제안, 코드 품질 개선 의견, 논리적 허점 탐색 등.
  - challenger.md를 적용해요.

3. 문서화 및 가이드 작성
  - JSDoc 작성, Storybook 스토리 생성, README 업데이트, 사용 가이드 문서 작성 등.
  - documenter.md를 적용해요.

4. 작업 내용 회고
  - 작업 마무리 후 회고 작성, 릴리즈 노트 준비 등.
  - retrospective.md를 적용해요.

5. UX 라이팅
  - 대고객/대유저 텍스트를 작성, 프로젝트 문서 작성, 블로그 포스트 작성 등.
  - writer.md를 적용해요.

 

 이렇게 세팅하고 나니, AI는 프롬프트를 받자마자 스스로 대화의 맥락을 분석하고 정해진 규칙에 따라 가장 적절한 역할을 골라 적용할 수 있게 되었습니다.

 

---

2.  라우터 패턴 적용 자동화

 라우터를 도입해 가장 큰 골칫거리를 해결한 줄 알았지만, 곧바로 새로운 장벽에 부딪혔습니다.

 개발자마다 활용하는 AI 코딩 도구가 다른데 (누구는 Claude, 누구는 Cursor), 도구가 바뀔 때마다 그 도구가 인식하는 공식 설정 파일의 위치나 이름이 전부 달라진다는 것이었습니다. 즉, 팀원 혹은 기여자들이 쓰는 도구 환경에 맞춰 똑같은 내용의 길잡이 문서를 매번 새로 만들고 복사해 줘야 하는 번거로움이 생겼습니다.

 매번 새로 만들고 복사를 해야한다면 휴먼 에러가 발생할 수 있을뿐더러 결코 좋지 않은 방식이라고 판단했습니다.

 저는 이를 해결하기 위해 쉘 스크립트와 Husky를 활용하여 라우터와 페르소나의 변경사항이 감지되면, 도구별 설정 파일들을 자동으로 동기화해주는 시스템을 구축하기로 했습니다.

 

2-1. 자동 동기화 스크립트 작성

 사람이 일일이 여러 AI 설정 파일을 만들어주는 건 매우 비효율적이고 휴먼 에러를 유발할 수 있습니다. 그래서 하나의 원본 길잡이 문서를 작성해두면, 팀원들 혹은 기여자들이 각자 쓰는 모든 AI 도구 전용 설정 파일들로 알아서 복사해 주는 '자동화 스크립트'를 작성했습니다.

# 각 AI 툴에 맞춰 생성/업데이트 될 규칙 파일들
TARGET_FILES=(
  "CLAUDE.md"
  "GEMINI.md"
  ".cursorrules.mdc"
)  # 이때, AI 규칙 파일들은 히스토리를 더럽히지 않도록 .gitignore에 추가

# 라우터의 내용을 AI 규칙 파일들에 생성/업데이트
for target in "${TARGET_FILES[@]}"; do
  cat "$ROUTER_FILE" > "$target"
done

 

 그리고 이 스크립트가 프로젝트 패키지들을 설치할 때(npm install 등) 자동으로 실행되도록 postinstall에 등록해 두었습니다. 이로써 처음 레포지토리를 마주하는 신규 팀원이나 기여자라도, 평소처럼 패키지 설치 명령어 한 번이면 본인의 AI 작업 환경이 자동으로 세팅되는 마법을 경험할 수 있게 되었습니다.

 

2-2. 규약 파일 업데이트 자동화하기

 그런데 원본 AI 규칙이 조금 수정될 때마다 팀원이나 기여자들에게 "스크립트 한번 다시 실행해 주세요!"라고 말하는 것조차 또 다른 불편함이 될 수 있습니다.

 그래서 코드를 저장(commit)하거나, 새로운 팀원의 작업을 받아올(pull) 때처럼 평소에 숨 쉬듯 쓰는 Git 명령어에 맞춰, 동기화 스크립트가 동작하도록 Husky를 활용했습니다.

• 커밋 직전(pre-commit): AI 규칙에 변경이 감지되면 즉시 팀원 혹은 기여자의 AI 규칙 파일에 동기화합니다.
• 작업 병합 직후(post-merge): 누군가 수정한 규칙을 내려받으면 즉시 AI 규칙 파일에 동기화합니다.
• 브랜치 변경 직후(post-checkout): 작업 단위마다 달라질 수 있는 규칙들을 놓치지 않고 AI 규칙 파일에 동기화합니다.

 이렇게 세팅해두니 평소처럼 개발만 해도 AI 작업 환경이 언제나 쾌적한 최신 상태를 유지하게 되었습니다.

 

---

얻은 성과

retrospective(회고) 페르소나 테스트 - Antigravity	challenger(평가) 페르소나 테스트 - Cursor

 이제 제가 의도했던 규칙대로, AI가 알아서 적절한 역할을 쓰고 템플릿 양식에 맞춰 "적용한 페르소나", "선정 이유", "주요 결과"를 깔끔하게 출력해주었습니다.

 

 더불어, AI 문서를 고치거나 작업 환경 이동시 AI 문서의 변경 사항을 감지했을 때, 모든 AI 규칙 파일들이 즉각 업데이트되는 것을 눈으로 확인할 수 있었습니다.

 이게 끝은 아닙니다. 앞으로 검증해보고 싶은 향후 과제는 "복잡한 맥락 안에서의 AI 판단력"입니다. 예를 들어 프롬프트 한 문장 안에 "기능을 개발하고, 관련 문서도 쓰고, 어떻게 구현했는지 회고까지 해줘"라고 다양한 맥락을 섞어서 던졌을 때, AI가 과연 가장 중요한 메인 역할과 보조 역할을 완벽하게 분리해 낼 수 있을지. 여러 엣지 케이스를 의도적으로 테스트해 보려 합니다.

 

---

에필로그 - AI는 도구가 아닌 팀원

 이번 작업을 통해 저는 AI를 단지 코드를 뿜어내는 '도구'가 아닌, 프로젝트의 원칙을 지키며 함께 일하는 '팀원'으로 정의할 수 있다는 AI-Native 개발의 첫걸음을 뗐습니다.

 앞으로 도입된 라우터 패턴을 통해 AI가 스스로 본인의 역할을 인지하고, 개발 환경을 일관성 있게 받쳐준다면, 개발자는 오롯이 '본질적인 문제 해결'에 집중할 수 있을 것이라 기대해 봅니다.

 

다음 편

2편: [AI] 지속가능한 AI 개발 환경 구축하기

 

참고 문서

- 소프트웨어 3.0 시대를 맞이하며: https://toss.tech/article/software-3-0-era

소프트웨어 3.0 시대를 맞이하며

- Software 3.0 시대, Harness를 통한 조직 생산성 저점 높이기: https://toss.tech/article/harness-for-team-productivity

Software 3.0 시대, Harness를 통한 조직 생산성 저점 높이기