팀의 제약에 맞춘
AI Native 개발환경

01

팀의 제약에서 시작한 설계

팀이 일하는 조건에 맞춰, AI와 함께 개발할 수 있는 환경을 만드는 것이 목표였습니다.

개발자는 9명이었지만, 사용할 수 있는 PC는 4대뿐이었습니다. 본사 DB만 사용하라는 지침이 있었고, 로컬 테스트에도 DB가 필요했습니다. 이슈와 설계, 주요 결정은 구두와 사내 메신저에 흩어져 작업을 시작하거나 이어받을 때 다시 찾아야 했습니다.

저는 PC가 바뀌어도 개발을 이어갈 실행 환경을 구성하고, 요청과 결정의 근거를 이슈와 주제별 노트로 연결했습니다. 이 지식을 AI가 작업에 활용하도록 하고, 반복 관리 자동화와 사람의 검토 절차를 함께 설계 · 구현했습니다.

02

실사용에서 드러난 문제와 개선

기능 변경마다 충돌하던 버전 규칙 정리

기능별 변경 검토 요청(MR)마다 버전을 올리면서 같은 파일의 병합 충돌이 반복됐습니다. 저는 기능 변경은 개별 기록으로 남기고, 버전은 릴리스 MR에서만 올리자고 제안했습니다.

기존 규칙은 버전 번호로 갱신을 감지하던 구조에서 생겼지만, 감지 기준은 이미 커밋 해시로 바뀐 상태였습니다. 변경된 규약은 버전 원본을 한 파일로 모으고 관련 파일을 재생성하며, 기능별 변경 기록을 릴리스 때 합치는 방식입니다.

생성물의 병합 드라이버는 상대 파일을 복사하고, 원본에서 관련 파일을 재생성하는 작업은 별도 단계로 두었습니다. 병합된 MR에는 드라이버를 적용한 검사와 릴리스 흐름이 통과하고, 드라이버를 제거한 대조군에서는 충돌이 재현됐다고 보고돼 있습니다.

실제 승인이 기록에서 빠진 문제

실제 업무에서 승인했는데도 시스템이 승인을 거부한 일이 있었습니다. SQLite 쓰기 잠금으로 사용자 입력 기록이 빠졌기 때문입니다. 저는 이 사례를 이슈로 정리하고, 입력 시각 보존 · 승인 수락 · DB 잠금과 독립된 실패 기록을 완료 조건으로 제시했습니다.

수정 구현에서는 DB를 열기 전에 입력 시각과 식별 정보를 파일에 보관하고, 잠금이 풀리면 원래 시각으로 중복 없이 반영하도록 바뀌었습니다. 실패 기록도 DB 밖에 남기고, 백그라운드 수집의 쓰기 작업을 나눴습니다. 원인을 구분하려면 먼저 측정 기록이 실제 입력을 보존해야 했습니다.

병합된 변경 기록에는 DB 잠금 재현을 포함한 13개 검사와 Windows PowerShell 호출 검증의 통과가 남아 있습니다. 전체 PC 적용과 실제 업무에서의 재발 감소는 확인하지 않았습니다.

03

요청과 결정이 남는 기록

사람과 AI가 작업할 때 같은 근거를 찾을 수 있도록, 흩어진 업무 지식과 개발 기준을 주제별 Markdown 노트로 정리했습니다. 한 노트에 한 주제를 다루고, 질문으로 확정한 사실과 출처 · 검증일 · 업무 영역을 함께 기록하도록 했습니다.

짧은 공통 규칙

항상 따를 규칙은 짧게 유지하고, 상세 업무 지식은 필요할 때 색인에서 찾아 읽도록 나눴습니다.

정본의 변경과 검토

노트를 수정하면 색인 생성과 정합성 검사를 거쳐 변경 검토 요청(MR)으로 넘기도록 구성했습니다.

팀 환경 동기화

지식과 함께 팀의 스킬 · 에이전트 · 훅을 설치 · 동기화해 다른 PC에서도 같은 기준으로 작업하도록 했습니다.

04

이슈부터 릴리스까지 자동화

변경 기록을 릴리스로 연결

GitLab CI와 팀 하네스를 활용해 이슈 관리, 태그 · 릴리스 등록, 패치노트 작성을 자동화했습니다. 각 업무에서 필요한 입력을 확인하고, 코드와 기록을 대조하는 절차를 도구에 담았습니다.

이슈 등록

작업 대상, 현재 상태와 기대 결과, 재현 방법과 배경을 확인합니다. 부족한 정보는 요청자에게 물은 뒤 이슈를 등록합니다.

릴리스 초안

직전 태그 이후의 이슈 · MR · 코드 변경을 대조합니다. 항목별 변경 내용과 경로, 입력, 확인할 결과, 배포 유의사항을 패치노트에 정리합니다.

승인 후 등록

초안을 사람이 확인하고 승인한 뒤 태그와 릴리스를 등록하도록 절차를 정했습니다.

05

AI의 수행과 사람의 검수

웹 시스템 개발에서는 이슈와 기존 상태, 관련 지식을 조회하고 작업공간과 Tomcat 환경을 준비합니다. 이어 AI가 구현 · 검사 · 화면 증적 작성을 수행하도록 연결했습니다.

저는 구현 결과가 이슈의 의도에 맞는지 작업자가 화면과 동작을 확인한 뒤 MR을 만들도록 정했습니다. 검수자는 MR의 변경 내용을 검토합니다. AI의 구현 · 검사와 사람의 의도 확인 · 변경 검토를 이 순서로 연결했습니다.

명세 · 설계 오류와 AI 구현 실패를 구분하는 측정

개발자의 명세 · 설계 오류와 Claude의 요건 이행 실패를 구분하는 것이 측정의 목적이었습니다. v2.7에서는 작업자의 첫 통과, 최종 검수 반려, 확인 질문과 재작업 사유를 기록하는 체계를 설계 · 구현했습니다.

원래 요청 · 착수 전 답변 · 합의된 기준을 구현 결과와 대조해 판정 근거를 남기고, 원인이 겹치거나 불명확하면 부원인 · 미확인 · 이견도 함께 기록하도록 했습니다.

06

작업 환경과 재개 흐름

지침상 본사 DB만 사용할 수 있었고, 로컬 테스트에도 DB가 필요했습니다. 사용하는 PC가 달라져도 본사 DB에 접근할 수 있어야 했습니다.

저는 Tailscale 라우팅을 활용해 PC를 본사 LAN에 직접 연결하지 않아도 본사 DB에 접근할 수 있도록 구성했습니다. 팀원이 PC를 옮겨도 개발과 로컬 테스트를 이어갈 수 있게 했습니다.

Git worktree별로 파일 · Tomcat 설정 · 포트를 분리하고, DB는 지침에 따라 공유했습니다. 검수 대기 중에는 해당 환경을 유지하고 담당자에게 화면 URL과 이슈 링크를 알리도록 구현했습니다.

PC를 옮길 때는 미커밋 변경과 인계 메모를 별도 Git 스냅샷으로 남기고 원격 저장소에 보관했습니다. 다른 PC에서 인계 문서와 변경 차이(diff)를 확인한 뒤 작업을 이어받는 흐름도 마련했습니다.

07

구현 · 도입과 확인 범위