「AI가 8할을 작성한 코드의 반년 운용」이라는 시리즈에서, 망가진(腐った) 3가지와 효과적인(効いた) 3가지를 꼽았습니다. 감사하게도 많은 분이 읽어주셨습니다.

• 정답 확인 본체 (효과적인 3가지 · 망가진 3가지): https://zenn.dev/rapls/articles/7a1bac83df8b21

다만, 그 기사에서는 「이것이 망가졌다」, 「이것이 효과적이다」라고 결과만을 나열했을 뿐, "무엇을 기준으로 그렇게 판정했는가"는 쓰지 않았습니다. 이번에는 그 척도(物差し)에 대한 이야기입니다. 망가졌다거나 효과적이라는 것은 감각으로 말한 것이 아니라, 제 안에 몇 가지 기준이 있었습니다. 그것을 글로 남겨둡니다.

먼저, 가장 큰 척도를 적겠습니다. 「반년 뒤의 내가 두려움 없이 만질 수 있는가」. 이것이 망가진 것과 효과적인 것을 나누는 가장 상위의 기준이었습니다. 만지는 것이 두려운 방향으로 흘러간 것이 망가진 것이고, 두렵지 않은 방향으로 작용한 것이 효과적인 것이었습니다. 다음은 그 「두려움」을 조금 더 세분화한 것입니다.

척도 1: 주석의 수명

망가짐을 판정할 때, 우선 주석을 보았습니다.

주석에는 수명이 있습니다. 코드를 단순히 말로 바꿔 쓴 주석은 구현을 바꾸는 순간 낡은 것이 되어, 결국 거짓이 됩니다. 수명이 짧습니다. 반면, 「왜 그렇게 했는가」를 적은 주석은 구현이 바뀌어도 의미를 유지합니다. 수명이 깁니다.

반년 뒤에 열었을 때 주석이 구현과 어긋나 있다면, 그것은 수명이 짧은 주석을 작성했다는 증거입니다. 망가진 부분에는 대개 수명이 짧은 주석이 늘어서 있었습니다. 이것이 첫 번째 척도입니다.

척도 2: 추상화가 새로운 케이스를 견뎌냈는가

너무 이른 공통화(Commonization)가 망가질지 여부는 시간이 지나면 알 수 있습니다.

판정은 심플합니다. 「만들었을 때 상정하지 않았던 케이스가 왔을 때, 그 추상화(Abstraction)가 견뎌냈는가」입니다. 견뎌내어 순조롭게 확장할 수 있었다면 그것은 좋은 추상화였습니다. 반대로 새로운 케이스를 흡수하기 위해 분기(Branch)가 늘어나고 함수가 비대해졌다면, 그것은 너무 이른 추상화입니다.

반년 동안 상정 외의 케이스는 반드시 옵니다. 그때 매끄럽게 추가할 수 있었는가, 아니면 억지로 끼워 넣었는가. 이 한 점으로 추상화가 효과적이었는지 망가졌는지가 명확히 갈렸습니다.

척도 3: 지시의 재현성

이것은 코드라기보다 AI에게 부탁하는 방식에 대한 판정입니다.

같은 요청을 며칠 뒤에 다시 AI에게 던졌을 때, 비슷한 품질의 것이 돌아오는가. 돌아온다면 그 지시는 구체적이며 기준이 언어화되어 있는 것입니다. 돌아오지 않는다면 그 지시는 「알기 쉽게」와 같이 애매한 것이며, 어쩌다 운 좋게 좋은 출력을 얻었을 뿐입니다.

통째로 맡기는 지시(丸投げ指示)가 망가지기 쉬운 이유는 재현할 수 없기 때문이었습니다. 한 번 잘 되더라도 다음에 같은 결과가 나오지 않습니다. 효과적인 지시는 몇 번을 던져도 대체로 비슷한 수준으로 돌아왔습니다. 재현할 수 있는지가 지시의 좋고 나쁨을 가르는 척도입니다.

척도 4: 설명할 수 있는가

가장 단적인 것은 이것이었습니다. 그 부분을 지금 스스로 설명할 수 있는가.

반년 뒤에 코드를 열고 「여기는 무엇을 하고 있는가」, 「왜 이렇게 작성했는가」를 막힘없이 설명할 수 있다면 그것은 몸에 익은 것입니다. 설명하려고 하는데 말이 막힌다면 그것은 스쳐 지나갔을 뿐, 자신의 것이 되지 않은 것입니다. 망가진 부분은 대개 제대로 설명할 수 없었습니다.

이것은 코드의 좋고 나쁨이라기보다, 내가 그 코드를 장악(把握)하고 있는지를 보는 척도입니다. 장악하지 못한 코드가 반년 뒤에 가장 두려운 부분이 되었습니다.

척도는 전부 「미래의 나」를 향하고 있다

나열해 보면 4가지 척도는 모두 같은 방향을 향하고 있었습니다. 반년 뒤, 1년 뒤의 내가 그 코드와 어떻게 지낼 수 있는가.

주석의 수명은 미래의 내가 읽었을 때 도움이 되는가. 추상화가 견뎌냈는가는 미래의 변경을 받아들일 수 있는가. 지시의 재현성은 미래에 다시 부탁할 수 있는가. 설명할 수 있는가는 미래의 내가 장악하고 있는가. 전부 지금의 내가 아니라 미래의 나를 기준으로 하고 있습니다.

아마 AI가 작성한 코드의 좋고 나쁨은 작성하는 순간에는 알 수 없습니다. 동작하는지 여부만 보일 뿐입니다. 망가졌는지 효과적인지는 시간이 흘러 미래의 내가 만졌을 때 비로소 판정할 수 있습니다. 그래서 척도 또한 미래의 나 쪽에 둘 수밖에 없었다고 생각합니다.

다음의 나에게 넘기는 메모

• 큰 척도는 「반년 뒤의 내가 두려움 없이 만질 수 있는가」
• 주석은 수명으로 본다. 말 바꾸기는 단명, '왜'는 장명
• 추상화는 「상정 외의 케이스를 견뎌냈는가」로 효과적/망가짐이 갈린다
• 지시는 재현성으로 본다. 같은 요청으로 같은 품질이 돌아오는가
• 가장 단적인 것은 「지금 설명할 수 있는가」. 막히는 부분이 미래에 가장 두렵다

「망가진 코드」와 「효과적인 코드」를 감각으로만 이야기하면 다음에는 활용할 수 없습니다. 이를 척도(Metric)로 삼아두면, 다음에 AI에게 코드를 작성하게 할 때 작성 직후에 "이것은 수명이 짧은 코멘트구나", "이 지시는 재현할 수 없겠구나"라고 그 자리에서 바로 깨달을 수 있게 되었습니다. 반년을 기다리지 않고도 판정할 수 있는 만큼, 코드가 망가지기 전에 고칠 수 있습니다.

이 시리즈의 전체 모습은 지도(Map) 기사에 정리해 두었습니다.

평소에는 raplsworks.com에서 WordPress 플러그인 개발이나 Claude Code 주변의 이야기를 쓰고 있습니다.

Discussion