Craftsman Coder: SOLID, AST CodeGraph 영향 분석, 증거 기반 엔지니어링은(는) 무엇을 하나요?
견고하고 분리된 검증 가능한 소프트웨어를 구축하기 위한 규율 있고 저장소에 구애받지 않는 엔지니어링 워크플로입니다.
핵심 원칙
- AST 및 CodeGraph 탐색 우선: 코드를 맹목적으로 수정하거나 리팩터링하지 마십시오. 구현을 변경하기 전에 항상 기호 정의, 호출자, 피호출자 및 폭발 반경(blast radius) 을 매핑하십시오.
- SOLID 및 단일 책임 원칙 (SRP):
모든 모듈, 함수 및 클래스는 변경되어야 할 단 하나의 이유만 가져야 합니다. 비즈니스 로직을 I/O, 지속성 및 외부 API와 분리하십시오.
- 분해 규칙: 하나의 컴포넌트, 클래스 또는 함수가 너무 길거나 여러 관심사를 처리하는 경우, 즉시 단일 책임을 가진 더 작은 원자적 하위 컴포넌트/서비스로 분해하십시오.
- 의존성 주입 (DI) 및 제어 역전 (IoC): 생성자 또는 프레임워크 메커니즘을 통해 의존성(리포지토리, 클라이언트, 로거)을 주입하십시오. 논리를 구체적인 인프라로부터 분리하십시오. 하드코딩된 직접 외부 인스턴스화를 피하십시오.
- 대체 아키텍처: 수직 슬라이스 아키텍처 (VSA) + EIP:
저장소에 확립된 프레임워크 관례가 없는 경우, 항상 수직 슬라이스 아키텍처 (VSA)와 SOLID 및 엔터프라이즈 통합 패턴 (EIP)을 함께 우선시하십시오:
- 수평적 기술 계층 대신 Request-Endpoint-Response (REPR) 패턴을 사용하여 비즈니스 기능별로 코드를 구성합니다 (
features/<feature_name>/). - 슬라이스 조정을 위해 EIP 패턴을 사용합니다: Command/Query 라우터, Pipes and Filters, Idempotent Receiver, Domain Event Pub/Sub.
- 상세 가이드: 수직 슬라이스 및 EIP 가이드
- 수평적 기술 계층 대신 Request-Endpoint-Response (REPR) 패턴을 사용하여 비즈니스 기능별로 코드를 구성합니다 (
- 결정론적 VSA 아키텍처 경계 린팅:
저장소가 VSA를 구현하는 경우, 결정론적 경계 린터(예: JS/TS용
dependency-cruiser, Python용import-linter, Go용depguard또는vsa_boundary_checker.py)를 구성하여 직접적인 크로스 슬라이스 임포트를 금지하십시오.- 상세 가이드: VSA 경계 강제 및 저장소 GEMINI.md 가이드
- 필수 저장소 수준
GEMINI.md(이식 가능 및 Git 준비): 저장소를 생성하거나 초기화할 때 항상 저장소 루트에 프로젝트 수준의GEMINI.md를 생성하여 아키텍처 선택, 경계 규칙 및 Gauntlet 명령을 유지하십시오.- 엄격한 이식성 규칙: 이 파일은 커밋되고 푸시되므로, 절대로 외부 호스트 경로(예:
~/.gemini/config/...,/data/data/...) 또는 머신별 비밀을 참조하지 마십시오. 반드시 100% 자체 포함되고 이식 가능해야 합니다.
- 엄격한 이식성 규칙: 이 파일은 커밋되고 푸시되므로, 절대로 외부 호스트 경로(예:
- 실시간 웹 연구 및 최적 Big-O 복잡성:
항상 최적의 Big-O 시간 및 공간 복잡성을 가진 알고리즘 및 데이터 구조 패턴을 선택하십시오 ($O(1)$ 조회, $O(N \log N)$ 정렬, 스트리밍 $O(1)$ 메모리).
- 필수 웹 연구: 지식이 오래되었을 수 있으므로 사전 훈련된 가정에만 의존하지 마십시오. 항상 현재 월과 연도를 기준으로 웹을 검색하여 최신 알고리즘 패턴, 최적의 데이터 구조 및 최신 고성능 라이브러리 구현을 발견하십시오.
- 고성능, 저메모리 라이브러리 및 엔터프라이즈 라이선스 준수:
- 최고 성능 및 낮은 메모리: 최신 캐시 친화적, 제로 카피, SIMD 가속 라이브러리(예:
orjson/msgspec,polars,sonic,zerolog,simd-json,fast-json-stringify)를 선호하십시오. - 엔터프라이즈 라이선스 준수: 관대한 오픈소스 라이선스(MIT, Apache 2.0, BSD-2/3, ISC)를 선택하십시오. 소스 공개 의무 없이 엔터프라이즈 감사를 통과하기 위해 바이럴 카피레프트(
GPL,AGPL,SSPL)를 엄격히 피하십시오. - 상세 가이드: 고성능 라이브러리 및 라이선싱 가이드
- 최고 성능 및 낮은 메모리: 최신 캐시 친화적, 제로 카피, SIMD 가속 라이브러리(예:
- SRP 및 추상화를 위한 결정론적 정적 코드 분석: SRP 위반(예: 비대한 길이, 과도한 책임) 및 추상화 우회(예: 프레젠테이션/비즈니스 로직 내부의 직접적인 원시 SQL 또는 HTTP 호출)에 대해 코드를 감사하기 위해 항상 결정론적 정적 분석 도구를 우선시하십시오.
- 중앙 집중식 비밀 주입 (Infisical):
비밀을 하드코딩하거나 git/로컬 env 파일에 원시 자격 증명을 저장하지 마십시오. Infisical (
infisical run -- ...)을 통해 비밀을 런타임에 주입된 의존성으로 취급하십시오.- 상세 가이드: Infisical 비밀 관리 가이드
- 프레임워크 관례 우선:
임시 추상화를 발명하기보다는 기존 프레임워크의 관용적 관례(예: FastAPI
Depends, NestJS@Injectable, React 훅, Go 인터페이스)를 존중하십시오. - 병렬화 가능한 격리된 테스트:
모든 테스트는 상태 비저장, 격리 및 병렬 준비(예:
pytest -n auto,go test -parallel)가 되어야 합니다. 공유 가능한 변경 가능한 상태나 정적 싱글톤 부작용이 없어야 합니다. - "Old Coder" 증거 기반 규율: 코드가 아닌 증거를 검토하십시오. Spec -> RED -> GREEN -> REFACTOR 루프를 따르고 작업 완료를 보고하기 전에 자동화된 터미널 검사를 통해 확인하십시오.
- AI 에이전트 준비 도구 및 스킬 엔지니어링:
반복되는 패턴을 도구와 스킬로 추출할 때:
--json출력, 비대화형 실행(프롬프트 없음),--dry-run안전성, 예측 가능한 명사-동사 동사 및 유형화된 종료 코드를 보장하십시오.- 상세 가이드: AI 에이전트 준비 CLI 설계 가이드
단계별 워크플로
1단계: 변경 전 폭발 반경 분석 (CodeGraph AST)
함수, 클래스 또는 서비스를 수정하기 전에 폭발 반경을 검사하여 다운스트림 영향을 확인하십시오:
python3 ~/.gemini/config/skills/craftsman-coder/scripts/codegraph_impact.py <path_to_repo> --symbol <TargetSymbol>
- 직접 호출자 및 참조 파일을 검토하십시오.
- 영향받는 테스트 스위트를 검토하십시오: 이 기호를 다루는 테스트가 없으면 리팩터링 전에 반드시 생성해야 합니다.
2단계: 아키텍처, 알고리즘 Big-O 및 저장소 수준 GEMINI.md
- 명확한 사양과 설계를 수립하십시오:
- 저장소를 생성/초기화하는 경우, 저장소 루트에 자체 포함된
GEMINI.md(외부 경로 없음, 비밀 없음)를 만드십시오. - 프레임워크 관례가 없으면, 수직 슬라이스 (
features/<name>/)로 REPR 및 EIP 패턴을 사용하여 구성하십시오. - 아키텍처 경계 린터 (예:
dependency-cruiser,import-linter또는vsa_boundary_checker.py)를 설정하거나 확인하십시오. - 클래스/함수/컴포넌트가 하나 이상의 일을 하거나 길이 임계값을 초과합니까? 집중된 하위 컴포넌트로 분해하십시오 (SRP).
- 외부 시스템이 강하게 결합되어 있습니까? 인터페이스/프로토콜을 정의하고 의존성 주입을 사용하십시오.
- 알고리즘 복잡성 및 웹 검색: Big-O 시간/공간 복잡성을 벤치마킹하십시오. 최신 알고리즘 최적화를 위해 현재 월과 연도별로 적극적으로 웹을 검색하십시오.
- 의존성 감사: 엔터프라이즈 안전 라이선스(MIT / Apache 2.0 / BSD)를 가진 저메모리, 고처리량 라이브러리를 선택하십시오. 카피레프트/AGPL 전이 의존성이 없도록 보장하십시오.
- 저장소를 생성/초기화하는 경우, 저장소 루트에 자체 포함된
- 상세 참조: SOLID 및 DI 패턴 가이드
- 상세 참조: 수직 슬라이스 및 EIP 가이드
- 상세 참조: VSA 경계 강제 및 저장소 GEMINI.md 가이드
- 상세 참조: 고성능 라이브러리 및 라이선싱 가이드
3단계: 병렬 실행 가능한 테스트 작성 (RED)
- 예상 동작 또는 버그 수정을 검증하는 격리된 비공개 단위 또는 통합 테스트를 작성하십시오.
- 테스트가 독립적인 임시 리소스 또는 인메모리 목을 사용하는지 확인하십시오.
- 테스트를 실행하여 실패(RED)하는지 확인하십시오.
- 상세 참조: 병렬 테스트 및 Old Coder 가이드
4단계: 최소한의 깔끔한 솔루션 구현 (GREEN)
- 테스트를 만족시키는 데 필요한 것만 구현하십시오.
- 컴포넌트를 응집력 있고 단일 목적으로 유지하십시오.
- 의존성을 깔끔하게 주입하십시오.
5단계: 리팩터링 및 Gauntlet (REFACTOR & EVIDENCE)
- 테스트가 계속 통과하는 상태에서 코드를 정리하십시오.
- Gauntlet을 실행하십시오 (모든 검증은 자동화되고 결정론적이어야 함):
- VSA 경계 검사:
아키텍처 경계 검사를 실행하십시오 (예:
npx depcruise --config .dependency-cruiser.js src또는python3 ~/.gemini/config/skills/craftsman-coder/scripts/vsa_boundary_checker.py <path_to_repo>). - 결정론적 정적 SRP 및 추상화 분석:
python3 ~/.gemini/config/skills/craftsman-coder/scripts/static_srp_analyzer.py <path_to_repo> --strict - 린터 및 정적 분석 (예:
ruff check .,eslint,golangci-lint) - 타입 검사 (예:
mypy,tsc --noEmit) - 전체 테스트 스위트를 병렬로 실행 (예:
pytest -n auto,go test -parallel 4 ./...)
- VSA 경계 검사:
아키텍처 경계 검사를 실행하십시오 (예:
- 최종 응답에 터미널 증거(종료 코드, 통과 테스트 요약)를 제공하십시오.
내장 스크립트 및 도구
-
CodeGraph AST 영향 분석기:
scripts/codegraph_impact.py- Python, JS/TS, Go, Rust, Java 전반의 AST 및 상호 참조를 검사합니다.
- 폭발 반경 위험 수준(낮음, 중간, 높음, 심각)을 계산합니다.
- 직접 호출자 및 영향받는 테스트 스위트를 식별합니다.
-
결정론적 정적 SRP 및 추상화 분석기:
scripts/static_srp_analyzer.py- SRP 길이/복잡성 위반에 대해 코드를 평가합니다.
- 추상화 우회(리포지토리/어댑터 외부의 원시 SQL/HTTP 호출)를 플래그 지정합니다.
- CI/Old Coder 검증을 위해 기계 판독 가능한
--json및 결정론적 종료 코드를 출력합니다.
-
VSA 아키텍처 경계 검사기:
scripts/vsa_boundary_checker.py- 불법적인 크로스 슬라이스 임포트를 방지하여 슬라이스 격리를 강제합니다.
.vsa-boundaries.json을 통해 구성 가능합니다. 의존성이 없으며 저장소에 구애받지 않습니다 (MIT).