▲

AI로 고품질 코드를 효과적으로 작성하는 방법

 (heidenstedt.org)
15P by GN⁺ 1일전 | ★ favorite | 댓글 1개
  • 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가 단계적으로 처리하도록 해야 함
    • 예: 전체 프로젝트 대신 개별 함수나 클래스를 생성
  • 각 구성요소가 명세에 부합하는지 검증해야 하며,
    코드의 복잡성을 통제하지 못하면 프로젝트를 초기 상태로 되돌려야 함
▲
GN⁺ 1일전  [-]
Hacker News 의견들

  • 나는 여전히 코드를 직접 작성하며 사고를 정리하는 과정이 중요하다고 느끼고 있음
    코드가 나에게는 세부사항을 다듬게 만드는 강제 장치 같은 존재임
    명세서를 쓰는 것만으로는 그 깊이를 얻지 못하는 느낌임

    • 나도 같은 생각임. 어릴 때부터 무언가를 직접 만들어보며 배우는 과정이 핵심이었음
      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를 열정적으로 옹호하는 모습이 아이러니함
    관련 트윗 링크에서는 이런 현상을 풍자함

    • “AI를 데이터로 오염시켜 방해하자”는 Underground Resistance 이야기도 있음
    • Claude의 성능 문제를 고치지 못하는 걸 보면 IPO를 앞두고 마케팅을 강화하는 것 같음
      “Claude 안 쓰면 뒤처진다”는 메시지가 그 이유일지도 모름
    • 많은 개발자들이 “AI 덕분에 생산성이 높아졌다”고 말하지만,
      실제로는 개발자 수요와 보상 감소로 이어질 가능성이 큼
      특히 단순히 NPM 패키지를 조합하는 수준의 개발자일수록 더 위험함
답변달기