lean-mode로 코딩 Agent를 위한 절제된 엔지니어링과 효율적인 검증 워크플로 구축

lean-mode란 무엇인가

lean-mode는 코딩 Agent를 위한 SKILL.md입니다. “코드는 적을수록 좋다”를 목표로 하지 않고, Agent가 다음 두 가지 엔지니어링 질문에 답할 수 있도록 명확한 기준을 제공합니다.

1. 검증, try/catch, 추상화 계층, 폴백 로직 또는 추가 보안 서브시스템처럼 겉보기에는 안전한 코드를 작성할 가치가 있는가?
2. 현재 빌드와 테스트가 느린 이유는 무엇이며, 비효율적인 검증 루프를 어떻게 합리적인 범위로 줄일 수 있는가?

스킬 파일은 skills/lean-mode/SKILL.md에 있으며, 표준 frontmatter, 즉 name, description과 Markdown 본문으로 구성됩니다. 특정 호스트에 종속되지 않으므로 SKILL.md 규약을 지원하는 모든 Agent에서 사용할 수 있습니다.

해결하려는 핵심 문제

장시간 코딩 세션에서 모델은 두 가지 체계적인 경향을 보이기 쉽습니다. 바로 과도하게 방어적인 프로그래밍과 비효율적인 검증 루프입니다.

과도하게 방어적인 프로그래밍

내부의 신뢰할 수 있는 데이터에 null 검사를 반복해서 적용하거나, 예외 처리로 근본 원인을 숨기거나, 단일 구현을 위해 미리 추상화를 만들거나, 문제의 원인을 확인하지 않은 채 폴백을 계속 추가하는 것이 대표적인 예입니다. 코드는 표면적으로 더 “안전해” 보이지만 실제로는 유지보수 비용을 높이고, 명확한 실패를 추적하기 어려운 오류 값으로 바꿀 수 있습니다.

비효율적인 검증 루프

전체 빌드를 자주 실행하거나, clean을 반복 사용하거나, 상주 프로세스를 비활성화하거나, 매번 모든 테스트를 실행하거나, 명백히 멈춘 명령을 오랫동안 기다리는 것이 대표적인 예입니다. lean-mode는 프로세스 재사용, 증분 실행, 범위 제어, 실행 순서, 호출 빈도, 타임아웃 관리라는 6가지 규칙으로 이러한 행동을 제한합니다.

README의 정량 데이터는 약 20k줄 규모의 Java 및 Gradle 프로젝트에서 진행한 한 번의 장시간 세션에서 얻은 것입니다. 문제의 실재를 설명하기 위한 자료일 뿐, 모델이나 프로젝트를 초월한 업계 기준으로 보아서는 안 됩니다.

주요 기능

• 신뢰 경계에서 한 번만 검증: 먼저 “이 null은 어디에서 왔는가?”에 답하게 하여, 신뢰할 수 있는 데이터가 시스템에 들어온 뒤에도 여러 계층에서 반복 검사되는 것을 방지합니다.
• 근본 원인을 삼키지 않기: catch 후 null, false, 빈 컬렉션 또는 0을 반환하는 패턴을 경계합니다. 명확한 예외를 추적하기 더 어려운 오류로 바꿀 수 있기 때문입니다.
• 성급한 추상화 제한: 구현이 하나뿐이거나 미래의 교체 가능성만을 이유로 만든 추상화는 실제로 안정적인 확장 경계를 형성하지 않을 수 있습니다.
• 근본 원인 우선 해결: 폴백을 추가한다는 것은 근본 원인이 아직 완전히 해결되지 않았다는 뜻입니다. 실제로 폴백이 필요하다면 문제의 귀속, 삭제 조건, 확인된 근거를 설명해야 합니다.
• 변경 규모를 동작 변화에 맞추기: 새 코드가 50줄을 초과하면 먼저 전체 줄 수, 검증 및 폴백에 사용된 줄 수, 해당 코드를 작성하지 않을 때의 실제 비용을 보고합니다.
• 안전한 코드를 작성하기 전에 세 가지 질문에 답하기: 문제가 실제로 발생할 수 있는가, 발생하면 사용자에게 어떤 영향이 있는가, 작성하지 않을 때의 비용은 무엇인가. 어느 질문에도 답할 수 없다면 먼저 코드를 추가하지 않습니다.
• 검증 루프 단축: Gradle, Maven, Go, Node 및 TypeScript, Rust, Python, .NET의 7가지 빌드 시스템에 적용할 수 있는 최소 검증 방식을 제공합니다.
• “수정하지 않음”이라는 결론 허용: 목표는 문제 해결이지 코드 작성을 강제하는 것이 아닙니다. 사용자가 요구하지 않은 영역을 임의로 강화해서도 안 됩니다.
• 기존 코드 감사 절차 제공: 먼저 밀도를 정량화하고, 가장 심각한 파일을 확인한 다음, 각 항목을 삭제, 상향 이동, 유지로 판단합니다. 수정 전에 결과 표를 사용자에게 제출합니다.

방어적 코드와 관련해 이 스킬은 Java, Go, TypeScript, Python 네 언어의 반례를 제공하여 Agent가 서로 다른 문법 뒤에 있는 동일한 문제를 식별하도록 돕습니다.

lean-mode 설치

방법 1: URL에서 가져오기

Vantaloom의 스킬 페이지처럼 호스트가 URL을 통한 스킬 가져오기를 지원한다면 저장소 주소를 바로 붙여 넣을 수 있습니다. 호스트는 skills/lean-mode/에서 스킬 파일을 찾습니다.

https://github.com/Timefiles404/lean-mode-skill

방법 2: 작업 공간에 복사하기

먼저 저장소를 클론한 다음, 호스트가 정한 위치에 스킬 디렉터리를 복사합니다. Vantaloom 작업 공간 규약을 사용할 때는 다음을 실행합니다.

git clone https://github.com/Timefiles404/lean-mode-skill.git
cp -r lean-mode-skill/skills/lean-mode <작업 공간>/.vantaloom/skills/

호스트가 Claude 스타일의 스킬 디렉터리를 사용한다면 .claude/skills/에 복사합니다.

cp -r lean-mode-skill/skills/lean-mode <작업 공간>/.claude/skills/

방법 3: 스킬 수동 생성

호스트에서 새 스킬을 만든 다음 저장소의 skills/lean-mode/SKILL.md 전체 내용을 붙여 넣습니다. 호스트는 description을 기준으로 스킬을 불러올 시점을 판단하므로 상단의 frontmatter를 빠뜨리지 마세요.

기본 사용 흐름

설치 후 lean-mode는 필요할 때 스킬 설명이 컨텍스트에 들어오는 방식으로 작동합니다. Agent가 검증, 예외 처리, 추상화 계층, 폴백 또는 추가 보안 서브시스템을 추가하려 하거나, 한 차례의 작업에서 빌드와 테스트를 여러 번 실행했다면 스킬이 활성화되어야 합니다.

상황 1: 새 검증이 필요한지 판단하기

1. 먼저 데이터의 출처를 추적하여 외부 입력, 인터페이스 경계 또는 기타 신뢰할 수 없는 출처에서 왔는지 확인합니다.
2. 동일한 제약 조건이 신뢰 경계에서 이미 검증되었는지 확인합니다.
3. 문제가 실제로 발생할 수 있는지, 사용자에게 어떤 영향이 있는지, 검증을 작성하지 않을 때의 비용이 무엇인지 답합니다.
4. 데이터가 내부로 들어온 뒤 이미 신뢰할 수 있다면 동일한 런타임 검증을 여러 계층에 반복해서 추가하지 않습니다.

예를 들어 Agent가 여러 내부 메서드에 Objects.requireNonNull을 반복해서 추가하려 한다면, 매개변수가 “이론적으로 null일 수 있다”는 이유만으로 추가해서는 안 됩니다. 먼저 null의 실제 출처를 추적하고 경계에서 검증이 이미 완료되었는지 판단해야 합니다.

상황 2: 예외 처리

Agent가 예외를 포착한 뒤 기본값을 반환하려 할 때는 먼저 이러한 처리가 근본 원인을 숨기는지 확인해야 합니다. 다음 패턴은 특히 주의해서 검토해야 합니다.

catch (...) {
    return false;
}

핵심은 모든 예외 처리를 금지하는 것이 아닙니다. 추적 가능한 실패를 맥락이 부족한 false, null, 빈 결과 또는 0으로 바꾸지 않는 것이 중요합니다. 비즈니스 요구상 장애 완화가 실제로 필요하다면 스킬의 예외 조건에 따라 계속 평가해야 합니다.

상황 3: 추상화 계층 평가하기

인터페이스에 현재 구현이 하나뿐이고, 생성하는 유일한 이유가 “나중에 교체할 수도 있기 때문”이라면 Agent는 잠시 멈추고 실제 변경 경계를 확인해야 합니다. lean-mode는 추상화 자체를 부정하지 않습니다. 현재 요구 사항과 안정적인 경계가 없는 상태에서 간접 계층을 미리 만드는 것을 반대합니다.

상황 4: 빌드와 테스트 단축하기

1. 기존 빌드 프로세스를 우선 재사용하여 불필요한 콜드 스타트를 반복하지 않습니다.
2. 증분 산출물을 유지하고 습관적으로 clean을 실행하지 않습니다.
3. 먼저 컴파일만 하거나, 관련 모듈만 검사하거나, 테스트 하나만 실행하는 최소 명령을 수행합니다.
4. 최소 검증이 통과한 뒤 모듈 테스트 또는 전체 테스트로 범위를 점차 확대합니다.
5. 반복 호출 빈도를 제어하여 코드 변경이 없을 때 동일한 명령을 반복 실행하지 않습니다.
6. 멈출 가능성이 있는 명령에는 합리적인 타임아웃을 설정하고, 실패하면 먼저 첫 번째 근본 원인을 분석합니다.

README의 전체 스킬 본문은 7가지 빌드 시스템에 대해 “이 명령 하나만 실행”하는 최소 검증 루프를 제공합니다. 실제 사용 시에는 이러한 예시를 프로젝트에서 직접 실행할 수 있는 실제 명령으로 우선 바꾸어야 합니다.

이미 과도하게 방어적인 코드 감사하기

lean-mode에는 이미 많은 검증, 폴백 또는 예외 무시 로직이 쌓인 프로젝트에 적합한 “먼저 측정하고 삭제하기” 감사 절차가 포함되어 있습니다.

1. 검색하고 정량화하기: 언어별로 부록의 검색 패턴을 사용하여 관련 패턴의 수와 밀도를 집계합니다.
2. 검사 범위 좁히기: 문제가 가장 집중된 5개 파일만 확인하여 처음부터 저장소 전체를 감사하지 않습니다.
3. 항목별 분류: 각 로직을 “삭제”, “상향 이동”, “유지”로 표시합니다. “상향 이동”은 보통 검증을 실제 신뢰 경계에 집중한다는 의미입니다.
4. 먼저 보고한 뒤 수정하기: 먼저 감사 표를 사용자에게 전달해 선택하도록 하고, 확인 없이 대규모 삭제를 진행하지 않습니다.
5. 나누어 검증하기: 수정 후 최소 범위의 빌드와 테스트로 검증한 다음 결과에 따라 범위를 확대합니다.

이 절차는 “방어 코드 줄이기”를 또 다른 통제되지 않은 대규모 리팩터링으로 만들지 않고, 관찰 가능하고 선택 가능하며 되돌릴 수 있는 작업으로 다루는 데 중점을 둡니다.

SKILL.md 사용자 지정

SKILL.md 자체가 Markdown이므로 직접 편집할 수 있습니다. 다음 세 가지 사용자 지정이 가장 유용합니다.

프로젝트 검증 명령으로 교체하기

7절의 일반 명령을 현재 프로젝트에서 실제로 실행할 수 있는 “컴파일만 하기” 및 “테스트 하나만 실행하기” 명령으로 바꿉니다. 바로 복사하여 실행할 수 있는 명령 하나가 추상적인 원칙보다 Agent의 행동을 제한하는 데 더 효과적인 경우가 많습니다.

검색 패턴 조정하기

프로젝트의 코드 스타일에 맞춰 부록의 검색 규칙을 수정합니다. 예를 들어 Java 프로젝트는 Guava의 Preconditions를 사용할 수도 있고, 주로 Objects.requireNonNull을 사용할 수도 있습니다. 검색 패턴은 실제 코드와 일치해야 합니다.

참고 밀도 조정하기

이 스킬은 200~500줄마다 검증 항목 하나가 나타나는 것을 경험적 참고 기준으로 삼지만, 이는 통일된 표준이 아닙니다. 파서, 프로토콜 경계, 비즈니스 CRUD의 적절한 검증 밀도는 서로 다르므로 도메인 위험과 데이터 출처에 따라 조정해야 합니다.

고급 사용 권장 사항

• 예외 조건도 컨텍스트에 유지하기: 스킬의 기준은 휴리스틱 규칙이지 정리가 아닙니다. “검증하지 말라” 또는 “catch하지 말라” 같은 단순한 구호만 남기지 마세요.
• Agent에게 변경 구성을 보고하도록 요구하기: 새 코드가 50줄을 초과하면 전체 줄 수, 검증 및 폴백 줄 수, 이러한 로직을 구현하지 않을 때의 비용을 명확히 설명하게 합니다.
• 검증 범위를 단계적으로 확대하기: 관련 파일, 단일 테스트 또는 모듈에서 시작한 뒤 더 넓은 테스트 범위로 이동하여 수정할 때마다 전체 빌드가 실행되지 않도록 합니다.
• 근거로 폴백 설명하기: 폴백을 유지해야 한다면 구체적인 문제 출처, 확인 결과, 향후 삭제 조건을 기록합니다. 검증할 수 없는 “일부 환경에서 오류가 발생할 수 있다” 같은 표현은 사용하지 않습니다.
• “수정하지 않음”을 유효한 결과로 취급하기: 기존 로직으로 문제가 이미 해결되었거나 새 코드의 이점이 명확하지 않다면 Agent가 수정할 필요가 없다고 바로 설명할 수 있어야 합니다.

기능의 한계와 선택적 보완 도구

lean-mode가 바꾸는 것은 모델의 경향이지 모델의 능력이 아닙니다. 특정 코드를 작성하지 않도록 모델을 강제할 수는 없으며, 적절한 시점에 기준을 컨텍스트에 제공할 뿐입니다. 따라서 효과는 있지만 보장되지는 않습니다.

또한 정적 분석기가 아니므로 코드를 자동으로 읽거나 스캔하지 않습니다. 부록의 감사 절차는 Agent가 해당 검색 명령을 직접 실행하고 결과를 바탕으로 판단해야 합니다.

선택 사항인 Vantaloom의 동명 플러그인은 압축된 규칙을 매 라운드 동적 컨텍스트에 지속적으로 추가하고, 도구 결과 주석과 lean_review 도구를 제공합니다. 플러그인은 지속적인 알림을 담당하고, 스킬은 완전한 판단 기준을 제공합니다. 플러그인을 설치하지 않아도 이 스킬은 독립적으로 사용할 수 있습니다.

프로젝트 저장소는 GitHub의 lean-mode-skill에서 확인할 수 있으며 MIT 라이선스를 적용합니다.

맺음말

lean-mode의 가치는 코드를 기계적으로 줄이는 데 있지 않습니다. 각 검증, 예외 처리, 추상화, 폴백, 검증 명령이 그 이유를 설명할 수 있도록 하는 데 있습니다. 설치 후 프로젝트의 실제 명령, 검색 패턴, 위험 밀도에 맞게 사용자 지정하면 코딩 Agent가 근본 원인에 더 집중하고, 더 짧고 신뢰할 수 있는 엔지니어링 피드백 루프를 구축하도록 도울 수 있습니다.