tdd-guide

tdd-guide skill 개요

tdd-guide가 적합한 작업

tdd-guide는 단위 테스트 생성, 커버리지 공백 탐색, fixture와 mock 작성, 그리고 일반적인 기술 스택에서 red-green-refactor 흐름을 안내하는 Test Driven Development용 skill입니다. AI assistant에게 단순히 “테스트 몇 개 작성해 줘” 수준을 넘어서, 소스 코드, 요구사항, 대상 프레임워크, 커버리지 리포트, 검증 기준까지 함께 다루게 하고 싶을 때 특히 유용합니다.

잘 맞는 사용자와 프로젝트

tdd-guide skill은 TypeScript, JavaScript, Python, Java로 작업하는 엔지니어링 팀, 1인 개발자, QA 중심 기여자에게 잘 맞습니다. 특히 Jest, Pytest, JUnit, Vitest, Mocha 스타일의 워크플로에 적합합니다. 기존 코드에 테스트를 추가하거나, 새 기능을 테스트 우선 방식으로 시작하거나, 특정 기준까지 커버리지를 끌어올리거나, 팀 전체의 테스트 출력 방식을 표준화하려는 상황에서 사용하기 좋습니다.

일반적인 테스트 프롬프트와 다른 점

일반적인 프롬프트도 그럴듯한 테스트를 만들 수는 있지만, 프레임워크 관례, 엣지 케이스, 커버리지 우선순위, TDD 사이클 자체를 놓치는 경우가 많습니다. tdd-guide에는 워크플로 구조, 샘플 입력, 기대 출력 패턴, 커버리지 분석 도구, fixture 생성, 프레임워크별 적용 방식, CI 통합 참고 자료가 포함되어 있습니다. 그래서 일회성 프롬프트 실험보다 반복 가능한 엔지니어링 작업에 더 적합합니다.

tdd-guide만으로는 부족할 수 있는 경우

tdd-guide for Test Driven Development는 도메인 동작을 이해하는 일을 대신해 주지 않습니다. 기대 결과, 의존성, 오류 규칙, 프레임워크 세부 정보를 제공할 수 없다면 생성된 테스트는 피상적일 수 있습니다. 또한 생성된 테스트가 사용자의 저장소에서 자동으로 컴파일된다고 보장하지도 않습니다. 로컬 테스트 명령을 직접 실행하고, import, setup 파일, mock, 환경별 설정을 조정해야 합니다.

tdd-guide skill 사용 방법

tdd-guide 설치와 저장소 미리보기

Claude Skills 호환 환경에서 다음 명령으로 skill을 설치합니다.

npx skills add alirezarezvani/claude-skills --skill tdd-guide

그다음 upstream skill 폴더인 engineering-team/skills/tdd-guide를 확인합니다. 활성화 규칙과 워크플로는 SKILL.md부터 읽고, 호출 예시는 HOW_TO_USE.md에서 확인하세요. 프레임워크별 설정이 필요하다면 references/framework-guide.md를 살펴보고, 빌드 강제 적용이 목표라면 references/ci-integration.md를 읽어보세요. 더 나은 TDD 습관을 만들고 싶다면 references/tdd-best-practices.md도 함께 검토하는 것이 좋습니다.

tdd-guide 사용 효과를 높이는 입력

이 skill은 네 가지 정보를 제공할 때 가장 잘 작동합니다. 코드 또는 기능 요구사항, 언어, 테스트 프레임워크, 기대 동작입니다. 좋은 입력에는 정상 경로, 오류 케이스, 경계값, 외부 의존성, 커버리지 목표가 포함됩니다.

약한 프롬프트 예시는 다음과 같습니다. “Write tests for my auth service.”

더 나은 프롬프트는 다음과 같습니다. “Use tdd-guide to generate Jest tests for src/auth/password-validator.ts. Cover valid password, too short password, missing uppercase, missing number, missing special character, and null or empty input. Target 90% branch coverage. Use existing project style: describe, beforeEach, and expect(...).toBe(...).”

실무에서 쓰기 좋은 tdd-guide 워크플로

기존 코드에 사용할 때는 다음 순서를 권장합니다.

1. 소스 파일을 붙여넣거나 참조합니다.
2. language, framework, 테스트 파일 명명 규칙을 지정합니다.
3. 테스트를 우선순위별로 묶어 달라고 요청합니다. P0 동작, P1 엣지 케이스, P2 회귀 테스트처럼 구분합니다.
4. 생성된 테스트를 로컬에서 실행합니다.
5. 컴파일 오류, 실패한 assertion, 커버리지 출력을 assistant에게 다시 붙여넣습니다.
6. import, mock, fixture, 누락된 branch를 다듬어 달라고 요청합니다.

새 기능을 만들 때는 red-green-refactor 흐름을 사용하세요. 먼저 인수 기준에서 실패하는 테스트를 요청하고, 이를 통과시키는 가장 작은 구현을 작성한 뒤, 테스트를 green 상태로 유지하면서 refactor-safe한 개선을 요청합니다.

먼저 살펴볼 파일과 스크립트

저장소에는 본격적으로 사용하기 전에 읽어볼 만한 실용적인 지원 파일이 포함되어 있습니다.

• assets/sample_input_python.json 및 assets/sample_input_typescript.json는 출력 품질을 높이는 구조화 입력의 수준을 보여줍니다.
• assets/expected_output.json는 이 skill이 생성하도록 설계된 테스트, 커버리지, 품질 요약의 형태를 보여줍니다.
• scripts/test_generator.py는 테스트 생성 패턴을 지원합니다.
• scripts/coverage_analyzer.py는 LCOV, JSON, XML 커버리지 데이터가 있을 때 관련됩니다.
• scripts/fixture_generator.py, framework_adapter.py, tdd_workflow.py는 이 skill이 mock, 프레임워크 관례, TDD 단계들을 어떻게 바라보는지 보여줍니다.

tdd-guide skill FAQ

tdd-guide는 초보자에게도 좋은가요?

네, 테스트할 구체적인 기능이나 함수가 있다면 좋습니다. tdd-guide skill은 red, green, refactor의 리듬을 익히게 해 주면서 실제로 쓸 수 있는 예시도 만들어 줍니다. 다만 초보자도 생성된 모든 테스트를 직접 실행하고 실패 내용을 읽어야 합니다. 학습 효과는 기대 동작, 생성된 assertion, 실제 구현을 비교하는 과정에서 나옵니다.

tdd-guide가 가장 잘 지원하는 프레임워크는 무엇인가요?

가장 잘 맞는 대상은 Jest, Pytest, JUnit, Vitest이며, skill 설명에는 Mocha도 언급되어 있습니다. 포함된 프레임워크 참고 자료는 TypeScript/JavaScript, Python, Java 패턴을 다룹니다. 덜 일반적인 프레임워크를 사용한다면, 저장소의 예시 테스트 파일을 함께 제공하세요. 그러면 skill이 import, 명명 방식, setup hook, assertion 스타일을 맞추는 데 도움이 됩니다.

커버리지 리포트를 분석할 수 있나요?

네. tdd-guide는 LCOV, JSON, XML 같은 커버리지 리포트와 함께 쓰도록 설계되어 있습니다. 가장 좋은 결과를 얻으려면 단순히 퍼센트만 제공하지 말고, 커버되지 않은 파일과 branch를 함께 붙여넣으세요. “coverage is 65%” 같은 프롬프트보다 coverage/lcov.info, 커버되지 않은 line range, 그리고 그 공백과 연결된 소스 파일을 공유하는 편이 훨씬 유용합니다.

언제 tdd-guide를 사용하지 않는 것이 좋나요?

보안에 민감한 동작, 금융, 의료, 컴플라이언스가 중요한 동작의 유일한 품질 게이트로 사용해서는 안 됩니다. 테스트 초안을 작성하고 공백을 드러내는 데는 도움이 되지만, 권위 있는 규칙 없이 비즈니스 정합성을 확인할 수는 없습니다. 코드베이스를 공유할 수 없거나, 공개적으로 정의된 동작이 없거나, 프로젝트가 숨겨진 통합 환경에 크게 의존하는 경우에도 잘 맞지 않습니다.

tdd-guide skill 개선 방법

더 나은 프롬프트로 tdd-guide 결과 개선하기

tdd-guide의 출력 품질을 가장 빠르게 높이는 방법은 코드만 주는 것이 아니라 동작을 함께 제공하는 것입니다. 유효한 입력, 유효하지 않은 입력, 기대되는 예외, 경계값, 기존 테스트 관례의 예시를 포함하세요. mock이 필요하다면 의존성 이름을 명시하고, 무엇을 stub 처리하고 무엇을 실제로 실행해야 하는지 구분해 주세요.

유용한 프롬프트 추가 문구는 다음과 같습니다.

• “Do not mock the pure calculation function.”
• “Mock the payment gateway and assert it is called once.”
• “Use parameterized Pytest cases for boundary values.”
• “Prefer behavior-focused test names over implementation names.”

첫 출력 이후 흔한 실패 패턴 수정하기

흔한 문제로는 잘못된 import, 과도한 mocking, 깨지기 쉬운 구현 세부 assertion, 누락된 async 처리, 신뢰도는 높이지 못한 채 line coverage만 올리는 테스트가 있습니다. 첫 결과를 받은 뒤에는 테스트 실패나 컴파일 오류를 붙여넣고, 범위를 좁혀 수정해 달라고 요청하세요. 예를 들면 다음과 같습니다. “These Jest tests fail because the service constructor requires a repository dependency. Revise using a typed mock and keep the same behavioral coverage.”

커버리지 데이터로 작업 우선순위 정하기

커버리지 개선이 목표라면, 커버되지 않은 모든 line에 대해 테스트를 생성하게 하기보다 risk 기준으로 공백을 순위화해 달라고 요청하세요. 단순한 getter나 방어적 branch보다, 테스트되지 않은 conditional, error branch, public method, business rule을 먼저 다루는 것이 좋습니다. 이 저장소의 커버리지 워크플로는 P0/P1/P2 우선순위를 지원하며, 원시 퍼센트만 쫓는 것보다 실무적으로 더 유용합니다.

유지보수 가능한 TDD 습관으로 반복하기

가장 좋은 tdd-guide 사용 방식은 반복입니다. 먼저 요구사항에서 실패하는 테스트를 요청하고, 다음으로 최소 구현 형태를 요청한 뒤, 테스트를 안정적으로 유지하는 refactor 제안을 요청하세요. assistant가 관찰 가능한 동작에 집중하도록 하세요. 즉 입력, 출력, side effect, 예외, 통합 경계에 초점을 맞추는 것입니다. 이렇게 해야 구현이 바뀐 뒤에도 계속 가치 있는 테스트를 만들 수 있습니다.