AI를 활용하여 개발 체계를 진화시키는 방법 기록

개인 개발 리포지토리에서 운영하고 있는 '개발 체계를 진화시키는 메커니즘'에 대해 정리합니다.

• 진화형 카드 TRPG 「카르타그래프(カルタグラフ)」

• 명세서 사이트 (VitePress) + 웹 앱 (React)

• 주로 작성하는 것은 AI 코딩 에이전트가 담당하고, 인간은 '결정'과 '확인' 역할을 합니다.

Note:

만들고 있는 것은 놀수록 규칙이 진화해 가는 카드 TRPG 「카르타그래프」입니다.
명세서 사이트와 웹 앱의 모노레포(monorepo) 구조로 되어 있습니다. 코드는 대부분 AI 에이전트에게 위임했습니다.

무엇을 만들지 결정하는 것과, 완성된 결과물을 확인하는 것이 인간의 역할입니다.

CLAUDE.md에 'heredoc으로 파일을 작성하지 말라'고 적었습니다.
↓

다음 PR에서 다시 heredoc으로 작성하여 망가뜨림

규칙을 읽게 하더라도, 주의력은 모델이나 그날의 상황에 따라 달라지기 때문에 취약합니다.

Note:

주의사항은 '읽고, 기억하고, 지킨다'는 AI의 주의력에 의존하고 있기 때문에, 모델이나 당일 컨텍스트(context)에 의해 쉽게 무너집니다.

후보 → 평가 → 채택 / 기각
(누구나) (인간이 심사) (기각도 이유와 함께 남김)

• 기록하는 곳은 1개의 파일입니다:
  docs/process/evolution.md

• 채택된 변경 사항에는 계기와 막는 방법을 반드시 작성합니다.

Note:

'진화 루프(進化ループ)'를 개발 체계에도 도입했습니다.
작업 중에 '규칙이 부족하다', '방해가 되었다'고 알게 되면, 인간이든 AI든 후보로서 진화 로그에 기록합니다. 이후 되돌아보는 과정에서 인간이 채택할지 기각할지를 결정합니다. 기각된 것도 지우지 않고 이유와 함께 남깁니다.

핵심은, 채택된 변경 사항에는 반드시 '무엇이 계기였는지', '어떻게 막을 것인지'를 작성하는 것입니다.

1. 플랜 작성 (AI가 질문하고 인간이 답변)
2. 플랜의 AI 리뷰
3. 테스트 포괄적 리뷰
...

되돌아보는 과정에서 나온 개선 사항이 다음 사이클의 규칙이 됩니다.

Note:

1개의 기능을 이 8단계 사이클로 만듭니다.
마지막 '되돌아보기' 단계에서 나온 개선 후보가 다음 사이클의 규칙이나 메커니즘이 됩니다.

개발 사이클 외부에, 체계를 키우는 또 다른 루프가 돌아가고 있습니다.

막는 방법을 4가지로 분류했습니다.

먼저 기계적으로 막을 수 있는지 생각한다. 규칙으로 끝낼 거라면, 그 이유를 작성한다.

Note:

개선 사항의 '막는 방법'은 4가지로 나누어 기록합니다.
가장 효과적인 것은 '기계적'으로 막는 것입니다. git hook, CI, lint, 빌드 시 검사 방침으로서, 개선안을 낼 때는 먼저 기계적으로 막을 수 있는지 생각하고, 문서의 규칙으로 끝낼 경우 '왜 기계적으로 하지 않는지'를 작성합니다.

인간이나 AI의 주의력에 의존하는 방식은 모델이나 담당자가 바뀌면 무너집니다.

실패 사례: sed -i

로 용어를 치환했더니, '작가(作者)' → '제작자(製作者)'가 두 번 적용되어 **'제제작가'**가 되었습니다.

테스트의 기대값도 같은 치환으로 망가져서, 테스트는 통과했습니다.
↓

• Claude Code의 훅에서 sed -i를 막고 – 치환은 replace-once.mjs로

'개수'와 '이중 적용(二重の当たり)'을 확인한 후에 작성하도록 했습니다.

계기: 작업 중 발생한 실패 / 막는 방법: 기계적

Note:

실제 사례 몇 가지를 소개합니다.
용어를 통일할 때 AI가 sed -i로 치환했더니, 같은 치환이 두 번 적용되어 '제제작가'라는 알 수 없는 단어가 생겼습니다. 게다가 테스트의 기대값까지 함께 망가져서, 테스트는 통과해버렸습니다.

주의사항에 의존하는 것이 아니라, Claude Code의 훅에서 sed -i 자체를 막고, 대신 개수를 선언하고 이중 적용도 검사하는 치환 스크립트를 사용하도록 했습니다.

실패 사례: '시나리오 작성자 / 제작자 / 작가'...

AI 리뷰가 매번 발견하고, 매번 수정했습니다.
↓

• 옛 명칭 목록을 가진 check-terms.mjs를 만들고 –
  pnpm docs:build 마지막 단계에서 빌드를 실패시킵니다 - pre-push · CI에서도 막힙니다.

계기: AI 리뷰 / 막는 방법: 기계적 (빌드 시 검사)

Note:

'작성자', '제작자', '작가'가 제각기 쓰여 있어서, AI 리뷰가 매번 그것을 발견하고 매번 수정했습니다. 리뷰에서 발견되는 것은 좋은 일이지만, 매번 같은 지적에 토큰을 쓰는 것은 아깝습니다.

이전 명칭 목록을 가진 검사 스크립트를 만들고, 문서 빌드 과정에서 실패하도록 했습니다.

실패: 체계를 바꿨는데도 진화 로그에 기록하는 것을 잊음
↓

.githooks/commit-msg

으로 막기

규칙・
AGENTS.md
・.claude/
・CI 등
을 바꿨는데도
진화 로그가 바뀌지 않은 커밋은 거부 - 필요 없다면
진화로그불필요: <이유>
를 쓰면 통과

Claude Code의 훅(hook)이 아니라 git의 훅 = 어떤 도구로든 적용 가능

Note:

세 번째는 다소 메타적인 이야기로, 진화 로그 자체의 누락 문제입니다.

체계를 바꿨는데도 로그에 기록하는 것을 잊은 경우가 있었습니다.
그래서 규칙이나 CI, .claude 하위 폴더 등을 바꿨는데 진화 로그가 바뀌지 않은 커밋은 commit-msg 훅으로 막도록 했습니다.

기록이 필요하지 않을 경우 '진화로그불필요'와 이유를 쓰면 통과합니다. 왜 기록하지 않았는지도 남습니다.

Claude Code가 아닌 git 훅을 사용한 이유는 어떤 도구로 작업하든 적용되게 하기 위함입니다.

채택 44건 (거부 4건)

기계적 검사로 막은 비율: 9월 62% → 10월 68%

Note:

한 달 동안 채택된 것이 44건, 거부된 것이 4건입니다.
막는 방식의 내역 중 기계적 검사가 29건으로 가장 많고, 44건 중 2/3은 기계적 검사로 막았습니다.

월별로 보면, 기계적 검사로 막은 비율이 조금씩 올라가고 있습니다.

• 진화 로그의 '계기'와 '막는 방식'을
  빌드 시에 읽어서 연표와 내역을 그리기 - 베껴 쓰지 않으니 이중 관리가 되지 않습니다.
• 서식이 망가졌다면
  빌드가 멈춥니다

docs/process/timeline.md ← evolution.md에서 생성

Note:

이 수치도 손으로 센 것이 아닙니다.

진화 로그의 '계기'와 '막는 방식'을 빌드 시에 읽어서, 사양서 사이트에 연표와 내역을 자동으로 출력하고 있습니다.

베껴 쓰지 않으니 이중 관리가 되지 않고, 서식이 망가져 있으면 빌드가 멈추므로 기록의 질도 기계적으로 지켜집니다.

• 진입점은 도구에 독립적인
  AGENTS.md

CLAUDE.md
는 그것을 읽기만 합니다.

.claude/
는 호출 지점이고, 절차의 본문은 docs/process/에 있습니다.

• 서브 에이전트의 model은
  inherit
  (고정하지 않음) - 작업마다
  **단계 (강함/표준/약함)**로 할당합니다.

Note:

또 하나 신경 쓴 부분은 특정 모델이나 도구에 의존하지 않는 것입니다.
진입점은 어떤 에이전트든 읽는 AGENTS.md로 하고, CLAUDE.md는 그것을 읽기만 합니다.
.claude 안의 스킬이나 서브 에이전트는 호출 지점으로 삼고, 절차의 본문은 리포지토리 문서에 두고 있습니다.

모델도 제품명으로 고정하지 않고, '강함・표준・약함' 단계로 작업마다 할당하고 있습니다.

이것 역시 토큰을 너무 많이 쓴다는 되돌아봄에서 시작된 변경입니다.

• 규칙과 사양이 모순되면 →
  멈추고 사람에게 물어봅니다 - 채택 / 거부의 재정 →
  사람 - 인간 리뷰는
  AI가 판정하지 않는 유일한 형태

AI가 제안하고, 기계가 지키며, 사람이 결정합니다.

Note:

모든 것을 AI와 기계에 맡기지 않습니다.
규칙과 사양이 모순되면 AI는 멈추고 사람에게 물어봅니다. 개선을 채택할지 여부는 사람이 결정합니다.

인간 리뷰는, AI에게 설명만 시키고 판정은 사람이 합니다.

AI가 제안하고, 기계가 지키며, 사람이 결정한다, 라는 역할 분담입니다.

• 실패는
  진화 로그에 '계기'와 '막는 방식'으로 남깁니다. - 막는 방식은
  규칙보다 기계적 검사(훅・CI・빌드 시 검사) - 지식은
  모델이 아니라 리포지토리에 둡니다.

주의사항을 늘리기보다, 같은 실패를 할 수 없는 시스템을 만듭니다.