시작
프로젝트를 위한 하네스를 만들어 보면서 느낀 점을 정리해 보고자 한다.
처음에 내가 접근했던 방식은, 안드레 카파시(Andrej Karpathy)가 작성한
지금은 171k 의 Start 를 가진 CLAUDE.md 의 규칙 4가지
- Think Before Coding
- Simplicity First
- Surgical Changes
- Goal-Driven Execution
이 네가지 항목을 통해 수행하도록 하되
놓친 부분이 있을 경우, 훅(Hook)을 통해서
해당 부분을 체크해 다시 수행할 수 있는 부분을 구성하고자 했다.
1차 Harness
AGENTS.md(CLAUDE.md) 파일에서는 위 4가지 규칙을 기준으로 하며,
작업을 수행할 때 5가지 Step 으로 구성해
각 Step 을 지날 때 마다 Hook(훅) 을 통해 각 단계가 규칙을 만족하는지 체크할 수 있게 구성했다.
Step 1. 계획 단계
일단, 내가 처음에 설계한 하네스의 범위는 기획이나, 디자인 관련된 부분은 프롬프트로 제공하거나,
미리 만들어진 항목을 가져다 쓰는 것으로 생각해 제시하는 것으로 생각했으며 한개의 커밋을 위한 항목이 아닌 경우 좀더 구체적으로 제시하게 하도록 하고 싶었다.
Step1-1 hook : check-work-type.sh - 작업의 workflow 확인
Step1-2 hook : check-scope.sh - 작업의 scope 확인
Step1-3 hook : check-plan-doc.sh - 작업 유형에 대해 계획 문서가 있는지 확인위를 통해 한가지 작업인지 확인 될 경우 2단계로 넘어가도록 했다.
Step 2. Spec 확인 단계
이 부분은, 계획된 작업을 수행할 경우, 어플리케이션 내 API Spec 이 달라지게 되면 영향도를 확인하기 위해 추가했다.
Step2-1 hook : check-spec-section.sh - 계획 내 스펙 영향도 확인이 있는지 체크
Step2-2 hook : check-spec-decision.sh - 계획 내 내/외부 스펙 영향 여부 체크
Step2-3 hook : check-spec-details.sh - 계획 내 스펙 영향도 상세 항목 체크 여부지금 보니.. 사실상 이건 계획에 대한 체크 뿐이 였다..
이 부분을 추가한 이유는 API 스펙이 변경되었을 때, 문서 업데이트가 되지 않는다거나 어플리케이션 내 외부 연동 API 를 포함하고 있을 경우 체크하는 부분이 필요할 것 같아서 만들었다..
Step 3. code 구현 단계
여기서는 실제 구현된 코드에 대한 검증을 수행했다.
Step3-1 hook : check-change-scope.sh - 변경 파일 계획 범위 일치 확인
Step3-2 hook : check-java-rules.sh - 변경 파일 자바 규칙 준수 확인
Step3-3 hook : check-tests-presents.sh - 변경 파일 테스트 존재 확인
Step3-4 hook : run-code-quality-tools.sh - 변경 파일 툴을 통한 체크계획에서 정한 항목이 변경되었는지를 확인하고
자바 규칙에서는 @Data 어노테이션을 사용하지 않는지,
controller, service 에서 New 를 사용하지 않는지, (정적 팩토리 메소드만 쓰도록..)
RestController 의 경우 ResponseEntity<ApiResponse>로 통일 하고 있는지를 확인했으며
테스트가 존재하는지 확인한 뒤,
Spotless, SonarQube 플러그인 을 gradle 을 통해 실행해 체크하고, checkStyle 을 통해서 변경된 파일들의 포맷을 맞쳐주는 항목을 실행하도록 구성했다.
Step 4. verify 단계
여기서는 코드를 test 실행을 통해 확인하는 단계이다
Step4-1 hook : run-gradle-test.sh - 실제 테스트 성공 확인
Step4-2 hook : check-jacoco-coverage.sh - 테스트 커버리지 준수 확인실제 테스트 수행을 통해 테스트가 성공하는지, 커버리지를 준수하고 있는지 이 단계를 통해 체크하도록 했다.
Step 5. commit 단계
Step5-1 hook : check-not-main-branch.sh - 메인 브런치에 대한 커밋이 아닌지 확인
Step5-2 hook : check-staged-files.sh - staged 파일 존재 확인
Step5-3 hook : check-commit-message.sh - 커밋메시지 확인여기서는 간단히 커밋이 메인 브런치에서 한 것인지와 변경된 파일들이 staged 되지 않았는지, 정도 체크하도록 했다.
후기
간단하게 Controller, Service, DTO 만드는 부분들 을 수행하는 부분은 만들어진 코드 스타일에 맞추어서 작업할 경우 속도도 빠르고 테스트도 준수하게 만들어 주었다.
하지만, 한번에 한개의 커밋만 해야 해 질문을 많이 수행해야 했으며, 간단하지 않은 로직을 만들고자 할 때는, 위 규칙을 지키고자 기괴한 코드를 만들기도 했다..
수정 방향성을 잡아주자 고치는 부분도 잘 하였어서 Step 3 의 규칙을 필요할 때 추가해서 쓴다면, 간단한 코드를 내 프로젝트 규칙에 맞게 만드는 용도로는 이 방식도 나쁘지 않겠다 라고 생각했다.
이후, codex 에 superpowers 와 같은 플러그인을 발견하면서 변경을 해보게 되었는데 이는 하네스 구성기 2를 통해 작성하겠다.
