# AI로 고품질 코드를 효과적으로 작성하는 방법 > Clean Markdown view of GeekNews topic #26491. Use the original source for factual precision when an external source URL is present. ## Metadata - GeekNews HTML: [https://news.hada.io/topic?id=26491](https://news.hada.io/topic?id=26491) - GeekNews Markdown: [https://news.hada.io/topic/26491.md](https://news.hada.io/topic/26491.md) - Type: GN+ - Author: [neo](https://news.hada.io/@neo) - Published: 2026-02-08T06:33:20+09:00 - Updated: 2026-02-08T06:33:20+09:00 - Original source: [heidenstedt.org](https://heidenstedt.org/posts/2026/how-to-effectively-write-quality-code-with-ai/) - Points: 40 - Comments: 1 ## Summary AI와 협업하는 개발 환경에서는 **명확한 비전과 문서화**가 품질의 핵심 축이 됩니다. 인간이 아키텍처와 의사결정을 선제적으로 정의하지 않으면, AI가 그 공백을 임의로 채워 예측 불가능한 결과를 낳을 수 있습니다. 또한 **디버그·리뷰·테스트 체계의 분리와 자동화**를 통해 AI가 생성한 코드의 신뢰성을 검증하고, 보안 위험 함수나 린팅 규칙을 명시적으로 관리해야 합니다. 이러한 구조적 통제는 AI의 생산성을 유지하면서도 코드 품질을 안정적으로 확보하는 기반이 됩니다. ## Topic Body - **AI와 협업하는 개발 환경**에서는 인간이 프로젝트의 방향과 의사결정을 명확히 정의해야 품질을 유지할 수 있음 - **정확한 문서화**를 통해 AI와 다른 개발자 모두가 요구사항과 제약을 명확히 이해하도록 해야 함 - **디버그 시스템과 코드 리뷰 체계**를 구축해 AI가 생성한 코드의 신뢰성과 검증 과정을 강화함 - **보안 위험 함수 표시, 테스트 분리, 엄격한 린팅 규칙** 등으로 코드의 안정성과 일관성을 확보함 - **작업 단위 분할과 복잡도 최소화**를 통해 AI 코드 생성의 통제력을 유지하고 효율성을 극대화함 --- ### 1. 명확한 비전 수립 - 인간은 세계와 팀, 사용자 행동을 이해하지만 **AI는 경험이 없으므로 명시적 지침이 필요함** - 프로젝트에서 문서화되지 않은 결정은 AI가 대신 내리게 됨 - **아키텍처, 인터페이스, 데이터 구조, 알고리듬**을 사전에 논의하고 테스트 방법을 정의해야 함 - 장기적이고 변경이 어려운 결정은 반드시 인간이 직접 관리해야 함 ### 2. 정확한 문서 유지 - AI가 목적에 맞는 코드를 생성하려면 **세부적인 요구사항 전달**이 필수임 - 다른 개발자도 동일한 정보를 AI에 제공해야 하므로, **표준화된 형식의 문서**를 코드 저장소에 포함해야 함 - 요구사항, 제약, 아키텍처, 코딩 표준, 디자인 패턴 등을 상세히 기록 - **UML 다이어그램, 플로우차트, 의사코드** 등을 활용해 복잡한 구조를 시각적으로 표현 ### 3. AI를 지원하는 디버그 시스템 구축 - **효율적인 디버그 시스템**을 마련해 AI가 코드 기능을 빠르게 검증할 수 있도록 해야 함 - 예: 분산 시스템의 모든 노드 로그를 수집해 “데이터가 모든 노드로 전송됨” 등 요약 정보를 제공 - 이를 통해 **명령어 실행 비용 절감**과 문제 식별 속도 향상이 가능함 ### 4. 코드 리뷰 수준 표시 - 코드의 중요도에 따라 **리뷰 강도를 구분**해야 함 - 예: AI가 작성한 함수 뒤에 `//A` 주석을 추가해 인간 검토 여부를 표시 - 이 체계는 **검토되지 않은 코드의 식별과 관리**를 용이하게 함 ### 5. 고수준 명세 작성 및 직접 테스트 - AI는 테스트 통과를 위해 **모의 객체나 하드코딩 값으로 속임수를 쓸 수 있음** - 이를 방지하기 위해 **속성 기반 테스트(property-based testing)** 를 직접 작성해야 함 - 예: 서버를 재시작하고 데이터베이스 값의 일관성을 검증 - 테스트 코드는 AI가 수정하지 못하도록 **별도 영역에 분리**해야 함 ### 6. 인터페이스 테스트의 분리 - **AI가 다른 코드 맥락을 모른 채 인터페이스 테스트를 작성**하도록 해야 함 - 구현 AI의 영향을 받지 않아 테스트의 객관성이 유지됨 - 이 테스트 역시 AI가 임의로 수정하지 못하도록 보호해야 함 ### 7. 엄격한 린팅 및 포맷팅 규칙 - **일관된 코드 스타일과 린팅 규칙**은 품질 유지와 오류 조기 발견에 필수적임 - AI와 인간 모두가 코드 품질을 쉽게 점검할 수 있음 ### 8. 컨텍스트별 코드 에이전트 프롬프트 활용 - **프로젝트별 CLAUDE.md 등 프롬프트 파일**을 사용해 AI의 초기 이해 비용을 줄임 - 코딩 표준, 디자인 패턴, 요구사항 등을 포함해 **AI의 코드 생성 품질과 효율성**을 높임 ### 9. 보안 위험 함수 식별 및 표시 - 인증, 권한, 데이터 처리 등 **보안 민감 함수**를 명시적으로 표시해야 함 - 예: `//HIGH-RISK-UNREVIEWED`, `//HIGH-RISK-REVIEWED` 주석 사용 - AI가 해당 함수를 수정하면 **리뷰 상태를 자동 변경**하도록 설정해야 함 - 개발자는 항상 이 상태가 정확한지 확인해야 함 ### 10. 코드 복잡도 최소화 - **불필요한 코드 한 줄**도 AI의 컨텍스트 창을 차지하고 비용을 증가시킴 - 가능한 한 단순한 구조로 유지해 **AI와 인간 모두의 이해도**를 높여야 함 ### 11. 실험과 프로토타입을 통한 문제 탐색 - **AI 코드 생성의 저비용 특성**을 활용해 다양한 해결책을 실험할 수 있음 - 최소한의 명세로 여러 프로토타입을 만들어 **최적의 접근법을 탐색**함 ### 12. 무분별한 대규모 생성 금지 - 복잡한 작업은 **작은 단위로 분할**해 AI가 단계적으로 처리하도록 해야 함 - 예: 전체 프로젝트 대신 개별 함수나 클래스를 생성 - 각 구성요소가 명세에 부합하는지 검증해야 하며, **코드의 복잡성을 통제하지 못하면 프로젝트를 초기 상태로 되돌려야 함** ## Comments ### Comment 50805 - Author: neo - Created: 2026-02-08T06:33:20+09:00 - Points: 1 ###### [Hacker News 의견들](https://news.ycombinator.com/item?id=46916586) - 나는 여전히 **코드를 직접 작성하며 사고를 정리하는 과정**이 중요하다고 느끼고 있음 코드가 나에게는 세부사항을 다듬게 만드는 강제 장치 같은 존재임 명세서를 쓰는 것만으로는 그 깊이를 얻지 못하는 느낌임 - 나도 같은 생각임. 어릴 때부터 **무언가를 직접 만들어보며 배우는 과정**이 핵심이었음 LLM에게 이런 과정을 맡기면 마치 비행기가 실속하는 것처럼 정신적으로 멈춰버림 문제 해결의 스트레스는 줄지만, 생각하고 창조할 동기가 사라짐 주변에서는 AI가 코드를 대신 써주는 걸 좋아하지만, 나는 그 그룹에 속하지 않음 - 나도 비슷하게 느끼고 있음. 커피 마시며 5개의 에이전트를 돌려 SaaS를 만든다는 사람들의 말을 믿기 어려움 좋은 품질의 코드를 원한다면 **직접 코드에 깊이 파고드는 과정**이 필요하다고 생각함 그래도 테스트 작성이나 설정 문제 해결 같은 **단순 반복 작업**에는 AI가 꽤 유용했음 예를 들어 5년 전 포기했던 프로젝트를 Claude로 다시 살렸는데, 몇 시간 만에 절반은 진척된 느낌임 - 나는 여전히 코드를 직접 검토하고 테스트함 다만 요즘은 **명세서 중심 접근**으로 돌아온 느낌임 에이전트 덕분에 시도와 포기가 빠르게 반복되어 여전히 **반복적 개발 흐름**을 유지할 수 있음 명세서와 테스트를 진짜 작업물로 보고, 그 안에서 계속 수정하며 생각을 정리함 - “코드가 세부사항을 다듬게 만든다”는 말에 완전히 공감함 명세서만으로는 현실의 복잡함을 다 담을 수 없음 LLM이 작성한 코드는 종종 **장황하고 이상한 방향으로 흘러가므로**, 직접 관리가 필요함 대신 LLM은 **아이디어를 토론하고 다듬는 파트너**로는 꽤 괜찮음 - 과거에는 소프트웨어 엔지니어링을 조립라인처럼 보려는 시도가 많았지만, 실제로는 **만들면서 설계하는 과정**이었음 이제 코드 작성이 싸지고 빨라진 만큼, 오히려 **정식 설계 단계**를 강화해야 할지도 모름 - 나는 **정적 분석 도구**를 체계적으로 세팅한 것이 코드 품질에 가장 큰 영향을 줬다고 생각함 TypeScript 기준으로 `tsc`, `eslint`, `sonarjs`, `knip`, `jscpd`, `dependency-cruiser`, `semgrep` 등을 조합해 `pnpm check` 명령으로 통합함 pre-commit hook으로 자동 실행되게 하여 LLM이 놓친 문제를 방지함 이 덕분에 LLM이 멈출 때도 쉽게 수동 수정이 가능함 - 나도 **엄격한 린트 규칙**을 적용하는 게 훨씬 쉬워졌다고 느낌 코드 스타일이 일관되면 리뷰가 훨씬 수월해지고, AI 코드와 사람이 쓴 코드가 섞여도 혼란이 줄어듦 - 나도 비슷한 세팅을 쓰고 있음. pre-commit hook은 필수임 다만 린트와 테스트를 모두 통과해도 **의도와 다르게 동작하는 코드**가 생김 예를 들어 404 대신 빈 배열을 반환하는 API처럼, 문법적으로는 맞지만 의미적으로 틀린 경우임 이런 **행동적 정확성 평가**가 아직은 가장 어려운 부분임 - LLM이 가끔 **결과를 거짓으로 보고**하는 경우도 있었음 - 좋은 구성임. 그런데 **최대 줄 길이 제한**은 왜 필요한지 궁금함. 삼항 연산자 때문인가? - 나는 오히려 코드의 **명확성 부족과 과도한 방어적 코딩**이 더 큰 문제라고 느낌 때로는 린트 규칙보다 유지보수성을 우선해야 한다고 생각함 - 나는 기능을 추가할 때마다 **정기적으로 리팩터링**을 함 몇 개 기능마다 코드베이스 전체를 점검하고 정리함 40년 동안 코딩을 해왔지만, 지금의 코드가 가장 만족스러움 - 과거에는 “작동하니까 그냥 배포하자”는 문화가 강했음 하지만 LLM 덕분에 **리팩터링 비용이 거의 0에 가까워짐** 이제는 나쁜 코드를 그대로 둘 이유가 없음 효율을 높이는 도구를 품질 향상에 쓰는 게 진짜 가치라고 생각함 - 나도 비슷한 교훈을 얻었음 커밋마다 코드 라인을 **좋음(초록)/리팩터 필요(노랑)/재작성 필요(빨강)** 으로 표시하는 내부 도구를 만들었음 “TODO refactor” 주석보다 깔끔하고 체계적이라 곧 오픈소스로 공개할 예정임 - 나는 지금 **AI와 함께 일하려면 명세 기반 개발**이 가장 안정적이라고 생각함 명세를 세밀히 다듬고 팀·AI와 아이디어를 주고받는 데 시간을 더 씀 명세가 불완전하면 AI가 엉뚱한 코드를 만듦 도메인 이해가 깊어지면 처음부터 다시 구현시키는 게 낫다고 느낌 - 이런 이야기를 들으면 90년대의 **UML, 4GL, Rational** 같은 꿈이 다시 떠오름 그때는 “요구사항만 정의하면 시스템이 알아서 만든다”는 비전이 있었음 결국 실패하고 애자일이 대세가 되었지만, 지금은 기술이 그 꿈을 다시 가능하게 만드는 듯함 - AI의 진짜 가치는 **속도와 모호함을 처리하는 능력**에 있음 하지만 모든 절차를 다 거치면 결국 워터폴처럼 느려짐 차라리 직접 코드를 쓰고 AI를 **1차 리뷰어**로 쓰는 게 낫다고 생각함 작은 단위로 빠르게 검증하며 진행하는 것이 여전히 **애자일한 접근**임 - 경험 많은 개발자에게도 유용한 아이디어가 많았음 특히 **보안 관련 함수 표시** 제안이 좋았음. 이후 코드 변경 시 문맥을 유지할 수 있음 “작게 나누기”는 기본이지만 초보자들이 자주 놓치는 부분임 - “이 모든 걸 하면 워터폴로 돌아간다”는 말에 농담으로 “다음은 바이브 기반 뇌수술이겠네”라고 덧붙임 - 요즘 사람들이 AI 덕분에 **기본적인 베스트 프랙티스**를 새삼 발견하는 게 웃김 사실 이런 건 예전부터 해야 했던 일임 - 하지만 현실적으로는 **출시 압박** 때문에 항상 지키기 어려웠음 이제 코딩 시간이 줄어들면서 이런 작업에 쓸 여유가 생김 게다가 AI는 **문서화를 실제로 활용**하므로, 문서를 잘 쓰는 게 직접적인 가치로 이어짐 과거엔 문서를 써도 무시당했지만, LLM은 다 읽음 - 이런 보호장치는 사실 **형편없는 프로그래머(혹은 앵무새)** 에게만 꼭 필요한 것임 - 예전엔 코딩 전에 **상세 명세서를 작성**했지만, 나중엔 코드로 바로 들어가는 게 더 빠르다는 걸 깨달았음 그런데 이제 다시 명세 중심으로 돌아가는 걸까? 문제를 완전히 이해하지 못한 상태에서 명세를 쓰면 결국 코딩하며 배우게 됨 지금 우리는 그 중간 어딘가에 있는 듯함 - 명세를 생략하면 종종 **완전히 잘못된 프로그램**을 만들게 됨 다만 이제는 AI 덕분에 잘못된 코드의 비용이 거의 0이라, 명세의 가치가 줄어든 느낌임 - AI가 코드를 싸게 만들어주니, 오히려 **명세 없이 먼저 시도하고 학습한 뒤 다시 설계**하는 방식이 가능해짐 이는 Joe Armstrong이 말한 프로그래밍 방식과 유사함 이제는 그게 현실적으로 가능한 시대임 - “계획하고 명세를 세운 뒤 코드를 작성해야 한다”는 말은 **언제나 진리였음** - 리드 포지션을 맡았을 때, 나는 **티켓을 매우 상세히 작성**했음 주니어를 위해서이기도 했지만, 나 자신이 세부사항을 잊지 않기 위해서였음 그러나 관리층은 “시간 낭비”라며 반대했고, 결국 그 습관을 잃었음 지금은 오히려 그보다 더 정교한 명세를 **더 빠르게** 쓰라고 요구받고 있음 - AI 에이전트를 쓸 때 **Markdown과 코드의 비율**, 그리고 결과물의 **가독성**이 궁금함 코드를 직접 쓰는 것보다 리뷰 시간이 더 걸리지 않는지도 의문임 - 요즘 개발자들이 자신을 대체할 수도 있는 AI를 **열정적으로 옹호하는 모습**이 아이러니함 [관련 트윗 링크](https://xcancel.com/hamptonism/status/2019434933178306971)에서는 이런 현상을 풍자함 - “AI를 데이터로 오염시켜 방해하자”는 [Underground Resistance](https://news.ycombinator.com/item?id=46827777) 이야기도 있음 - Claude의 **성능 문제**를 고치지 못하는 걸 보면 IPO를 앞두고 마케팅을 강화하는 것 같음 “Claude 안 쓰면 뒤처진다”는 메시지가 그 이유일지도 모름 - 많은 개발자들이 “AI 덕분에 생산성이 높아졌다”고 말하지만, 실제로는 **개발자 수요와 보상 감소**로 이어질 가능성이 큼 특히 단순히 NPM 패키지를 조합하는 수준의 개발자일수록 더 위험함