6개월 전 「AI가 80% 작성한 코드를 유지보수할 수 있도록 하고 있는 것」이라는 기사를 썼습니다. 감사하게도 제가 가장 많이 읽힌 기사가 되었습니다.

그로부터 6개월, 그 방침 그대로 실제로 운용해 보며 정답을 확인할 수 있었습니다. 결론부터 말하자면, 유지보수성은 「더하기」로는 살 수 없었습니다. 코멘트를 더하고, 문서를 더하고, 깔끔한 추상화 (Abstraction)를 더하는 것. 그 대부분은 6개월 후에 부패해 있었습니다. 효과가 있었던 것은 소수의 「효과적인 형태」뿐입니다.

이 기사에서는 좋다고 생각해서 더했지만 무용지물이었던 3가지를 먼저 쓰고, 그 후에 6개월 후에도 효과가 있었던 3가지를 쓰겠습니다. 전편이 「해야 할 일」에 관한 기사라면, 이 글은 「하지 않아도 좋았던 일」에 관한 기사입니다.

효과가 없었던, 부패한 3가지

불공평하므로, 실패한 대책부터 쓰겠습니다.

1. AI가 덧붙인 대량의 코멘트와 docstring

가장 많이 부패했습니다. AI는 부탁하면 얼마든지 코멘트를 작성합니다. 반년 전의 저는 「설명이 많을수록 친절하다」고 생각하여, 코멘트를 잔뜩 넣게 했습니다.

하지만 그 대부분은 코드를 일본어로 바꾸어 말했을 뿐인 설명이었고, 구현을 변경할 때마다 코멘트만 옛날 내용 그대로 남겨졌습니다. 6개월 후에 다시 읽어보니 코멘트와 코드가 어긋나 있었습니다. 도움을 줄 것이라 믿었던 설명이 거짓 지도가 되어 있었습니다. 지금은 AI가 덧붙인 이런 종류의 코멘트는 발견하는 대로 지우고 있습니다.

2. 너무 이른 공통화와 깔끔한 추상화

AI는 「공통화합시다」, 「추상화해 두었습니다」라는 제안을 자주 합니다. 겉모습이 정돈되어 보이기 때문에 당시에는 그 제안을 따랐습니다.

6개월 후, 새로운 케이스가 나타났을 때 그것이 역효과를 냅니다. 너무 이른 추상화는 예상하지 못한 분기 (Branch)에 맞지 않고, 그렇다고 떼어내기도 어렵습니다. 중복을 방치해 두는 편이 오히려 변경이 가벼웠던 장면이 여러 번 있었습니다. DRY (Don't Repeat Yourself)를 목적으로 만든 공통화가, 떼어낼 수 없는 결합 (Coupling)이 되어 있었던 것입니다.

3. 「알기 쉽게 써줘」라는 무책임한 요청

이것은 효과가 있다고 착각했을 뿐이었습니다. AI에게 「유지보수하기 쉽게」, 「알기 쉽게」라고 모호하게 부탁하면, 겉모습만 정돈된 다른 코드가 돌아옵니다. 변수명이 그럴싸해져서 왠지 좋아진 것 같은 기분이 듭니다. 하지만 6개월 후에 만져보니 유지보수성은 단 1mm도 움직이지 않았습니다. 추상적인 지시는 추상적인 만족감만을 돌려줄 뿐입니다.

효과가 있었던 3가지

여기서부터는 6개월 후에도 제대로 효과가 있었던 것들입니다. 수는 적습니다.

1. 「왜(Why)」만을 코멘트로 남기기

무엇을 하는가가 아니라, 왜 이렇게 했는가. 이것만은 효과가 있었습니다. AI가 작성한 코드는 동작은 하지만 의도를 읽을 수 없습니다. 6개월 후의 제가 가장 곤란한 상황은 「이거 왜 이렇게 썼더라?」 하는 순간인데, 거기에 한 줄이 있느냐 없느냐에 따라 코드를 만질 때의 두려움이 완전히 달랐습니다. 코멘트를 줄이고 「왜」만을 남기는 것. 이것이 생명줄이었습니다.

2. 함수 1개의 책임을 작게 다시 나누기

AI는 하나의 함수에 처리를 크게 몰아넣어 작성합니다. 생성 직후에는 동작하기 때문에 그대로 두기 쉽습니다. 하지만 6개월 후에도 두려움 없이 만질 수 있었던 것은, 제가 작게 다시 나누어 놓은 함수뿐이었습니다. 커다란 덩어리는 어디를 바꾸면 무엇이 망가질지 읽을 수 없어 만지는 것이 꺼려집니다. 나누는 작업은 수수하지만, 6개월 후의 나에게 주는 효과는 가장 확실했습니다.

3. 사양과 테스트는 인간이 쥐고 있기

구현은 AI에게 맡기더라도, 사양 (Specification)과 테스트만큼은 스스로 쥐고 있었습니다. 이것이 가장 효과적이었던 한 가지입니다. 망가지지 않는 축이 하나 있으면, 구현을 AI에게 몇 번이고 다시 쓰게 해도 그 축을 기준으로 돌아올 수 있습니다. 반대로 사양까지 모호한 채로 AI에게 맡긴 부분은, 다시 쓸 때마다 조금씩 동작이 어긋나 6개월 후에는 무엇이 옳은지 스스로도 알 수 없게 되었습니다.

결국, 더하기보다 빼기였다

나열해 보니 명확해졌습니다. 부패한 것은 전부 「더한」 것들이었습니다. 코멘트, 추상화, 그럴싸한 지시. 효과가 있었던 것은 깎아내고 남긴 소수의 형태였습니다. 「왜」만을 남기기, 작게 나누기, 축을 하나 쥐기. 모두 늘리는 방향이 아닙니다.

반년 전의 저는 유지보수성을 「더하면 살 수 있다」고 생각했습니다. 실제로는 반대로, 더한 것일수록 부패하기 쉽고 깎아내고 압축한 것만이 남았습니다. AI는 얼마든지 더해 주기 때문에 내버려 두면 더하는 방향으로 흐릅니다. 그렇기에 의식적으로 빼야 합니다. 이것이 6개월 운영의 정답 확인이었습니다.

다음의 나에게 전달하는 메모

• AI가 과하게 작성하는 주석은 변경 사항과 어긋나 거짓 지도가 된다. "왜(Why)"만 남기고 나머지는 지운다.
• 너무 빠른 공통화(Commonization) 및 추상화(Abstraction)는 반년 뒤에 떼어낼 수 없는 결착(Adhesion)이 된다. 중복을 허용하는 편이 더 가벼울 때도 있다.
• "알아보기 쉽게 써줘"라는 식의 무책임한 요청은 겉모습만 다듬을 뿐 유지보수성(Maintainability)은 개선하지 못한다.
• 효과가 있었던 것은 "왜"를 남기기, 작게 나누기, 사양(Specification)과 테스트를 인간이 쥐기, 이 3가지뿐이었다.
• 유지보수성은 더해서 살 수 없다. AI는 더하는 방향으로 흐르기 때문에 의식적으로 빼야 한다.

전편에서 "하고 있는 일"에 대해 썼지만, 6개월이 지난 지금 가장 효과적이었던 것은 "하지 않기로 결정한 것"이었습니다. 다음에 올 6개월 뒤의 내가 곤란해하지 않도록, 이것도 남겨둡니다.

평소에는 raplsworks.com에서 WordPress 플러그인 개발이나 Claude Code 관련 내용을 쓰고 있습니다.

Discussion