AI Assistant와 함께 코드 품질을 레벨업

Source: Dev.to

(번역을 진행하려면 전체 텍스트를 제공해 주시겠어요?)

Current State

이 게시물은 5년 넘게 활발히 유지 관리되지 않았지만 여전히 활발히 사용되는 제품을 실행하고 있는 실제 코드베이스를 소개합니다. 비즈니스에 필수적이지만 필요한 안전망이 갖춰져 있지 않았습니다. 프롬프트를 포함한 여정을 하나씩 진행하면서 이 저장소의 코드 품질을 어떻게 개선할 수 있는지 살펴보겠습니다.

이 프로젝트는 API를 제공하는 Django 백엔드 애플리케이션입니다. 간단히 살펴보면 테스트와 일부 문서는 존재하지만, 애플리케이션을 실행하고 테스트하는 일관된 방법이 없습니다.

여정

대부분의 경우 Claude Sonnet 4를 사용하고 있다고 가정하고, Claude Code를 이용해 이 명령들을 실행하고 있다고 가정합니다. 동일한 접근 방식은 어떤 코딩 어시스턴트에서도 작동하지만, 결과는 모델, 프롬프트 및 코드베이스에 따라 달라질 수 있습니다.

기본 문서화 및 일부 자동화 설정

Claude Code와 같은 도구를 사용하고 있다면, 저장소에서 /init 명령을 실행하면 이 문서의 상당 부분을 자동으로 생성할 수 있습니다.

Can you analyse the code and write up documentation in README.md that
clearly summarises how to set up, run, test and lint the application.
Please make sure the file is concise and does not repeat itself.
Write it like technical documentation. Short and sweet.

다음으로 프로젝트 사용을 편리하게 만들 just 파일과 같은 자동화 스크립트를 설정합니다. 올바르게 만들기까지 몇 차례 시도가 필요할 수 있지만, 아래 프롬프트를 시작점으로 사용할 수 있습니다.

Please write up a just file. I would like the following commands:
`just setup` – set up all the dependencies of the project  
`just run`   – start up the application including any dependencies  
`just test`  – run all tests  

If you require clarifications, please ask questions.
Think hard about what other requirements I need to fulfill.
Be critical and question everything.
Do not make code changes till you are clear on what needs to be done.

이렇게 하면 빠르게 수정할 수 있는 기본 구조가 제공됩니다. README.md에 이미 애플리케이션 실행 방법(로컬 vs Docker)이 명시돼 있다면, just 파일이 자동으로 이를 사용합니다; 그렇지 않다면 추가 설명을 제공해야 합니다.

조기 피드백을 위한 pre‑commit 설정

작게 시작하고 점차 확장해 나갑니다.

Please setup pre‑commit with a single task to run all tests on every push.
Update the just script to ensure pre‑commit hooks are installed locally
during the setup process.

컨텍스트를 작게 유지하고 작업을 명확히 하면 더 빠르게 진행할 수 있습니다.

코드 품질 도구 선정

먼저 좋은 도구를 찾고, 계획을 만든 뒤 실행합니다. Claude Code를 Plan mode(Shift + Tab 두 번)로 전환하고 다음과 같이 물어보세요.

What's a good tool to check the complexity of the Python code in this
repository and lint it to provide the team feedback as a pre‑commit hook?

어시스턴트가 도구 세트를 제안할 것입니다. 기술 부채가 많은 대규모 코드베이스에서는 바로 녹색 빌드를 기대하기 어렵습니다. 요청을 다듬어 보세요.

The list of tools you suggested sounds good.
The codebase currently has a very large number of violations.
I want the ability to incrementally improve things with every commit.
How do we achieve this?

계획 수립

이전 프롬프트를 반복해서 다듬으면 구체적인 실행 계획을 받을 수 있습니다. 어시스턴트가 실행하기 전에 “저장 상태”(비디오 게임의 세이브와 같은)를 만들어 두어, 문제가 발생하면 롤백할 수 있도록 합니다. 이렇게 하면 모든 컨텍스트가 마크다운 파일로 디스크에 저장돼 컨텍스트가 정리됩니다.

Can you create a plan that is executable in steps?
Write that plan to `docs/code-quality-improvements`.
Try to use multiple background agents if it helps speed up this process.

어시스턴트가 코드를 분석하는 데 몇 분 정도 걸립니다. 제 경우에는 다음과 같은 파일들이 생성되었습니다. 생성된 README.md에는 “동일 단계 내의 작업은 전제 조건이 충족되는 한 여러 Claude Code 어시스턴트에 의해 병렬로 실행될 수 있다”는 내용이 포함됩니다.

개요

/clear 를 눌러 컨텍스트 창을 비울 준비가 되었습니다.

작업별 계획

• Phase 1 – 기본 도구를 설정합니다
• Phase 2 – 도구들을 구성합니다
• Phase 3 – 통합 및 자동화에 집중합니다
• Phase 4 – 모니터링을 추가하고 코드 품질을 향상시킵니다

계획을 실행하기 전에 docs/code-quality-improvement에 커밋하세요. 이렇게 하면 이루어진 모든 변경 사항을 추적할 수 있습니다. 계획을 실행할 때는 계획에 대한 변경 사항을 체크인 하지 마세요; 프로세스가 끝난 후에 계획을 삭제할 수 있습니다.

계획을 아티팩트로 보관하고 싶다면 Claude Code에 상대 경로를 사용하도록 요청해야 합니다(계획에서 파일을 업데이트하도록 요청할 때 기본값은 절대 경로입니다).

Executing the Plan

I would like to improve code quality and I have come up with a plan to do 
so under `docs/code-quality-improvement`.
Can you analyse the plan and start executing it? The `README.md` has a 
quick‑start section which tasks about how to execute different phases of the 
plan. As you execute the plan, mark tasks as done to track state.

Note: Claude Code will add dependencies to requirements-dev.txt and try to run things without installing them. It may also add non‑existent dependencies.
Stop the execution (press Esc) and use the following prompt to course‑correct:

For every pip dependency you add to `requirements-dev.txt`, please run 
`pip install`. 
Before adding a dependency to the dependency file, please check if it is 
available on pip.

After Phase 1 & Phase 2

다음 파일들이 생성되었으며 커밋할 준비가 되었습니다.

Phase 3에서 품질 게이트를 추가하면, 명령을 한 번 실행해 모든 것이 정상 작동하는지 테스트하고 또 다른 커밋을 생성하세요. 그 후 Claude Code에게 린트 단계를 간소화된 개발자 경험에 통합하도록 요청합니다:

Please add `just lint` as a command to run all quality checks

새로운 lint 명령을 테스트한 뒤 커밋하고 Claude Code에게 Phase 4 진행을 요청하세요.

Claude Code가 자신이 만든 계획에 의문을 가질 수도 있습니다. 시스템은 정상적으로 동작하지만, 더 고급 검사를 원한다면 Phase 4 구현을 계속 진행하도록 요청하세요.

Phase 4 이후 결과

레포지토리는 이제 개발자가 코드를 푸시할 때마다 코드 품질을 검사합니다:

• Pre‑commit hooks가 푸시 전에 린팅을 실행합니다.
• 변경된 파일에 다음이 포함되어 있으면 품질 검사가 실패합니다:
  • 포맷이 맞지 않은 코드
  • 잘못된 순서의 import
  • flake8 린트 문제
  • 사이클로마트 복잡도가 높은 함수

수정된 파일만 검사됩니다 (우리는 Claude에게 기존 부채가 존재하므로 모든 검사가 기본적으로 통과되지 않을 것이라고 말했습니다).

기존 부채 해결

isort와 같은 도구는 많은 문제를 자동으로 강조하고 수정할 수 있습니다. 대부분의 코드베이스에서는 거의 모든 파일이 영향을 받게 됩니다. 자동으로 해결할 수 없는 문제(예: 와일드카드 임포트)는 수동으로 해결해야 합니다.

비용 팁: 문제가 많이 발생하면 Claude Code를 사용하는 비용이 많이 들 수 있습니다(규모가 적당한 코드베이스의 경우 $10 이상이 될 수 있음). 비용을 절감하려면 GitHub Copilot의 에이전트로 전환하는 것을 고려하세요.

권장 워크플로우

1. 코딩 어시스턴트에게 lint 명령을 실행하고 문제를 수정하도록 요청합니다.
2. 어시스턴트가 몇 차례 시도 후 멈춘다면, lint 오류가 남지 않을 때까지 작업을 계속 진행하도록 지시합니다.
3. 컨텍스트 파일(CLAUDE.md)에 lint 방법이 명시되어 있지 않다면, 정확한 명령을 명시적으로 제공하세요.

남은 것?

gradual-tightening 작업은 코드를 분석하고 점점 더 엄격해지는 명령을 생성합니다. 수동으로 또는 CI 파이프라인에서 자동으로 실행할 수 있습니다. 이 작업의 매개변수 중 하나인 max‑complexity는 기본값이 20이며 시간이 지남에 따라 감소될 예정입니다.

마찬가지로, complexity‑check 작업은 낮은 기준으로 시작하며 저장소의 품질 기준을 높이기 위해 주기적으로 엄격해져야 합니다.

대체로 마지막 단계는 우리 팀원 모두가 걸어야 합니다.
이제 우리는 파이프라인을 실패시키고 코드가 커밋되거나 푸시되는 것을 막는 나쁜 코드에 대한 강력한 피드백 메커니즘을 갖추었습니다.
마지막 부분은 팀 문화가 구축되어야 합니다. 제가 속한 팀 중 하나에서는 매 회고마다 모든 팀원이 스프린트 동안 코드베이스를 조금이라도 개선했는지 부드러운 체크를 했습니다. 스프린트는 10일이며, “조금이라도”는 2~3줄짜리 작은 함수를 리팩터링하여 개선하는 것을 포함할 수 있습니다. 기준은 정말 낮지만, 무언가를 더 좋게 만들고 싶다는 사회적 압력이 우리 모두를 긍정적인 변화를 이끌게 했습니다.
고품질 코드베이스와 좋은 개발자 경험을 갖는 것은 꿈이 아니라, Claude Code나 Copilot 같은 AI 코딩 도우미 덕분에 현실이 되기 쉬워졌습니다.
최근에 무엇을 개선했나요? 😃