Claude Code (Opus 5.5)로 기능 추가 시 기존 기능이 손상되는가? 하네스(Harness)와 대응 프롬프트를 비교하며

검증에 사용한 앱은 여기입니다. 마작 패를 터치하면 점수와 부(符)의 내역이 나옵니다.

AI로 만든 앱에 기능을 추가했을 때, 기존 기능이 어딘가에서 손상되는지 확인해 보았습니다. 저의 마작 앱인 '부나비'에서 조건을 3가지로 변경하여 각각 2회씩 시도했습니다. 작업은 Claude Code를 사용했으며, 모델은 Claude Opus 5.5입니다.

결론부터 말씀드리자면, 3가지 조건 모두 기존 기능이 손상된 곳은 0곳이었습니다. 차이가 난 부분은 코드의 양과 사양(specification)의 정확도였습니다.

| A: 하네스 없음 | B: 하네스 있음 | C: B + 대응 프롬프트 | |
|---|---|---|
| 손상된 기존 기능 | 0 | 0 | 0 |
| ...

계기: Zenn의 'GUI가 망가져 가는' 글

2026년 9월, Zenn에서 다음 글이 자주 읽혔습니다. AI에게 화면을 만들게 할 때마다 기능을 추가할 때마다 화면들끼리 간섭하여 망가지는 경우입니다. 이에 대한 대책으로 설계 패턴을 한 문장으로 압축한 프롬프트를 소개하는 글이었습니다.

소개된 프롬프트는 다음과 같습니다.

모든 컴포넌트를 Root에서 비롯되는 계층 구조 아래에 배치하고, 각 컴포넌트는 MVP(Model-View-Presenter) 패턴의 Passive View로서 렌더링과 관련된 파라미터만 조작하며, 동작은 Chain of Responsibility로 이벤트를 버블링시키고, 스테이트 머신으로 작동하는 Mediator가 심사하도록 할 것.

마침 부나비에 부 계산 연습 문제(드릴)를 추가하려고 했습니다. 계산 화면 옆에도 또 하나의 화면을 추가하는, 처음의 큰 기능이었습니다. 어차피 만들 거라면, 이 프롬프트가 효과가 있는지 제 앱에서 확인해 보기로 했습니다.

대상 앱과 '하네스'

부나비는 HTML/CSS/TypeScript(프레임워크 없음) 웹 애플리케이션입니다. 제작 당시의 이야기는 다른 글에 썼습니다.

개발 과정에서는 AI가 지켜야 할 규칙을 CLAUDE.md 또는 .claude/rules/에 모아둡니다. TDD(Test-Driven Development) 절차, 레이어 간 의존 방향(ui → application → domain), 완료의 정의(테스트와 타입 체크 통과 등) 등이 포함됩니다. AI를 외부에서 지지하는 시스템이므로 최근에는 '하네스(Harness)'라고 불립니다.

실험 설계

3가지 조건

• A: 하네스 없음. CLAUDE.md 및 .claude/rules/와 설계서를 제외함 -
  B: 하네스 있음. 평소대로 작업
  C: 하네스 있음 + 위 대응 프롬프트

A 조건에서도 기존의 테스트 코드와, 계산·화면·상태를 분리한 폴더 구조는 그대로 유지했습니다. 제거한 것은 AI용으로 작성된 문서 규칙만입니다.

이전 조건에서 배운 내용이 섞이지 않도록, 조건별로 기억하지 못하는 별도의 에이전트를 세우고, 각기 다른 작업 복사본으로 동시에 만들게 했습니다.

요청문 (1회차)

3가지 조건 모두 동일한 요청문을 사용했습니다.

부나비에 '부 계산 드릴'을 추가해 주세요. 무작위로 성립된 패와 조건을 출제하고,
사용자가 부를 선택하여 답하면, 정오답과 부의 내역이 표시되는 연습 모드입니다.
현재 점수 계산 화면은 그대로 사용할 수 있도록 하고, 화면상에서 계산과 드릴을 전환할 수 있게 해 주세요.

검사 절차는 결과 보기 전에 결정했다

손상되었는지 여부를 AI의 자체 진술로 판단할 수는 없습니다. 작업이 끝나기 전에 검사 절차를 정하고 로그에 기록해 두었습니다. 결과를 보고 나서 기준을 바꾸지 않기 위해서입니다.

• 기존 테스트 1,087개 통과 및 타입 체크·빌드 성공
• 스마트폰 폭의 브라우저에서 계산 화면에 동일한 패를 넣어 점수가 변하지 않는지 확인 (롱(ロン) 30 부 2,000점, 쯔모(ツモ) 20 부 2,700점)
• 드릴을 갔다가 돌아온 후에도, 패·용어 해설·드라 입력이 동일하게 작동하는지
• 드릴을 10문제 연속으로 풀어도 멈추지 않는지

브라우저에서의 검사는 Claude Code에 작성시킨 스크립트로 자동화했습니다.

1회차: 3가지 조건 모두 손상되지 않았다

| A | B | C | |
|---|---|---|
| 시간 | 13.3분 | 21.8분 | 31.5분 |
| ...

차이가 컸던 것은 C였습니다. 대응 프롬프트에 따라 기존 화면의 구성 요소 6개를 지시된 구조로 다시 작성했습니다. 새로운 기능을 추가하기 위해, 작동하는 화면을 처음부터 다시 만든 것입니다.

두 번째: 화면 간 연결 기능 추가

이 정도만으로는 '이 정도 기능으로는 고장나지 않는다'고 생각할 수 있습니다. 그래서 두 번째는 고장 나기 쉬운 요청을 했습니다.

드릴 정답 확인 화면에 '점수 계산으로 열기' 버튼을 추가해 주세요.
버튼을 누르면 점수 계산 화면으로 전환되고, 해당 문제의 패・떨어짐(鳴き)・화료패・조건이 입력된 상태로
점수가 표시되도록 해 주세요.
...

d릴 상태를 계산 화면에 흘려보내기 때문에, 두 개의 화면 상태가 직접 연결됩니다. 원래 기사에서 문제 삼았던 '화면 간의 간섭'이 가장 발생하기 쉬운 형태입니다. 점검을 위해 '드릴 풀기 → 계산 화면으로 열기 → 부(符) 대조 → 드릴로 돌아가기'를 10문제 반복하는 절차를 추가했습니다.

두 번을 합친 결과로 C는 A에 비해 시간이 2.0배, 토큰이 1.7배, 코드가 2.4배였습니다. 다만 C가 적었던 수치가 하나 있습니다. AI가 도구를 호출한 횟수에서, C는 39회, A는 43회, B는 48회였습니다. 미리 재작성한 구조가 조금 효과를 발휘하기 시작했을지도 모릅니다.

차이가 난 것은 '고장 여부' 때문이 아니었다

드릴 정답 결정 방식

마작의 패는 면(面子)을 나누는 방식에 따라 부(符)가 달라질 수 있습니다. 같은 14장의 패라도, 같은 패 3장의 조합(刻子)으로 볼지, 이어지는 숫자 3장의 조합(順子)으로 볼지에 따라 부가 다릅니다.

A와 C는 점수가 가장 높아지는 방식의 부를 정답으로 했습니다. 이렇게 하면 다른 방식으로 정확하게 계산한 사람이 오답이 될 수 있습니다.

B만은, 어떻게 나누어도 부가 같아지는 패만 출제하도록 했습니다. 연습 문제에서 가장 피해야 할 것은, 정확히 답한 사람을 오답으로 만드는 것입니다. B는 그 점을 피했습니다.

하네스(Harness) 테스트 규칙에는 '여러 면子 분해가 가능한 패로, 가장 높은 부가 선택됨'이라는 체크 항목이 있습니다. B는 이것을 읽고, 나누는 방식에 따라 부가 달라질 수 있는 패가 있다는 것을 깨달았는지도 모릅니다. B가 남긴 설계 기록에도 '해석에 따라 부가 달라지는 패를 출제하면, 정확하게 계산한 사람이 오답이 될 수 있다'고 있었습니다. 다만 각 조건 1회씩의 결과이기 때문에, 하네스 덕분이라고 단정하기는 어렵습니다.

인간에게 판단을 돌려주었나

B는 두 번째 작업 보고서 마지막에 이렇게 썼습니다. 성적을 기기(브라우저)에 저장하도록 했지만, 개인정보 보호정책에는 '입력한 패나 조건은 기기 안에서만 계산에 사용한다'고만 쓰여 있습니다. 추가할지 여부는 판단해 달라는 내용입니다. 약관의 문구였기 때문에 임의로 바꾸지는 않았다고 합니다. A와 C는 언급하지 않았습니다.

이 지적을 계기로, 성적 기능 자체를 다시 생각하게 되었습니다. 연습에는 정답 확인과 부 내역만 있으면 충분합니다. 성적은 필요하지 않다고 판단하여 기능을 아예 없앴습니다. 기기에는 아무것도 남지 않으므로, 개인정보 보호정책은 현재 그대로 정확합니다.

점검 스크립트도 두 번 틀렸다

점검 스크립트에서도 두 번 걸렸습니다.

첫 번째는 용어 해설과 드라 입력이 3개 조건 모두 '열리지 않는다'고 판정된 경우였습니다. 스크립트가 용어 해설의 ⓘ 버튼을, 드라를 넣는 버튼으로 착각했던 것이 원인이었습니다.

두 번째는 B와 C의 10문제 전부에서 '드릴 정답과 계산 화면의 부가 일치하지 않는다'고 나왔습니다. B와 C는 올바른 선택지 뒤에 '정답' 표시를 해 두었고, 스크립트는 그 다음 버튼의 숫자를 읽었던 것입니다. 실제로는 정답과 계산 화면의 부가 정확히 일치했습니다.

둘 다 Claude Code가 직접 스크린샷을 찍어 알아차리고 수정했습니다. 숫자만 보고 'B와 C는 고장났다'고 썼다면, 이 기사는 거짓이 되었을 겁니다. AI의 '고장나지 않았다'도 '고장났다'도, 화면으로 확인하기 전까지는 가설입니다.

알게 된 것

가장 크게 깨지지 않은 이유는 프롬프트 밖에 있었다고 생각합니다. A는 규칙의 문장을 제외하더라도 1,087개의 테스트와 계산/화면/상태를 분리한 폴더 구조를 남겨두었습니다. AI는 이 테스트들을 통과하면서 작업했기 때문에, 만약 깨진 부분이 있다면 테스트에서 멈춥니다. 이는 추측이며, 확실히 하려면 테스트가 없는 앱으로 같은 작업을 해봐야 합니다.

대응 프롬프트는 이미 구조가 있는 앱에는 너무 무거웠습니다. 적힌 대로 다시 만들기 때문에 변경이 커집니다. 원래 기사가 예상하는 것은 화면끼리 실제로 간섭하여 깨지기 시작한 앱입니다. 그런 앱에 사용하면 결과가 다를 것입니다.

차이가 난 부분은 사양의 정확성과 인간에게 돌려줘야 할 판단이었습니다. 고장 나지 않았는지는 기계로 확인할 수 있습니다. 하지만 '제대로 답한 사람이 오답이 되지 않는지', '규약을 바꿀지'는 무엇을 옳다고 정의할지를 결정한 사람만이 판단할 수 있습니다.

최근 모델들은 성능이 높아 지시가 적어도 상당히 잘 만들어 줍니다. 그만큼 조건이 바뀌어도 깨지는 수에는 차이가 나기 어려울 수도 있습니다.

기능을 추가하기 전에, 점검 절차를 작성하기

AI에게 기능을 추가하도록 할 때마다 무언가가 고장 나서 곤란하다면, 프롬프트를 고안하기 전에 현재 작동하는 것의 확인 방법을 3~4줄로 적어보세요. '이 입력이라면 몇 점', '이 화면으로 갔다가 돌아와도 입력이 남아있다' 정도면 충분합니다.

그것을 요청할 때마다 AI에게 전달하고, 끝나면 자신도 같은 절차로 만져봅니다. 거기서 시작하는 것이 좋습니다.

이번 드릴은 B 버전에서 성적 기능을 빼내어 점수 내비게이션에 넣었습니다. 화면 상단의 '점수 계산 드릴'에서 시도할 수 있습니다.

Discussion