기본 Skill 1 - feature-clarifier

해당 Skill은 사용자의 막연한 요청을 바로 코딩하지 않고 개발 가능한 작업으로 변환합니다.

 

경로 : .agents/skills/feature-clarifier/SKILL.md

 

---
name: feature-clarifier
description: 막연하거나 범위가 불분명한 기능 요청, 변경 요청, 버그 요청을 실제로 구현할 수 있는 작은 작업으로 구체화한다. 작업 범위, 제외 범위, 제약조건, 완료 조건, 영향받는 영역, 위험요소, 테스트 계획을 정리한다. 요청이 광범위하거나 모호하거나 여러 파일에 영향을 줄 가능성이 있을 때 코딩 전에 사용한다. 이 Skill을 사용하는 동안에는 코드를 수정하지 않는다.
---

# 목적

사용자의 비공식적이거나 막연한 요청을 검토 가능하고 테스트 가능한 개발 작업으로 변환한다.

# 필수 행동 규칙

1. 코드를 수정하지 않는다.

2. 프로젝트의 `AGENTS.md`와 요청에 가장 가까운 관련 문서를 읽는다.

3. 요청과 관련된 기존 코드를 확인하고 현재 시스템이 어떻게 동작하는지 파악한다.

4. 코드와 문서에서 확인된 사실과 아직 확인되지 않은 추측을 구분한다.

5. 구현 방식이나 작업 범위를 크게 바꿀 수 있는 누락된 정보가 있는지 확인한다.

6. 불필요하게 넓은 작업 범위나 대규모 재작성 계획이 포함되어 있다면 이를 지적한다.

7. 하나의 작업으로 독립적으로 개발하고 검증할 수 있는 가장 작은 변경을 우선한다.

8. 아래에 정의된 출력 형식에 맞춰 결과를 작성한다.

# 필수 출력 형식

## 목표

이번 작업을 통해 정확히 어떤 동작이 변경되어야 하는지 설명한다.

## 현재 동작

확인한 코드와 문서를 근거로 현재 시스템이 어떻게 동작하는지 설명한다.

코드를 확인하지 못한 내용은 현재 동작으로 단정하지 않는다.

## 작업 범위

이번 작업에 반드시 포함해야 하는 기능과 동작만 작성한다.

## 작업 제외 범위

요청과 관련은 있지만 이번 작업에는 포함하지 않아야 하는 기능과 변경사항을 작성한다.

범위가 불필요하게 커지는 것을 방지하기 위해 명확하게 구분한다.

## 관련 파일 및 모듈

변경 가능성이 있는 다음 항목을 정리한다.

- 파일
- 패키지
- React 컴포넌트
- Spring Boot 클래스
- API
- 데이터베이스 Migration
- 테스트
- 설정 파일
- 관련 문서

아직 확정되지 않은 파일은 변경 대상이라고 단정하지 말고 예상 대상이라고 표시한다.

## 제약조건

작업 중 반드시 지켜야 하는 제약조건을 작성한다.

필요에 따라 다음 내용을 포함한다.

- 기존 아키텍처
- 기존 코딩 패턴
- 하위 호환성
- UI 표준
- 보안과 권한
- 성능
- 외부 연계
- 데이터베이스
- 사용 가능한 의존성
- 변경하면 안 되는 영역

## 가정

아직 코드, 문서 또는 사용자 답변으로 확인되지 않았지만 작업 계획을 세우기 위해 임시로 가정한 내용을 작성한다.

가정을 확인된 사실처럼 표현하지 않는다.

## 확인 질문

답변에 따라 구현 방식, 데이터 구조, 권한, API 계약 또는 작업 범위가 실제로 달라지는 질문만 작성한다.

사소하거나 코드 확인으로 해결할 수 있는 질문은 사용자에게 묻지 않는다.

질문이 없어도 작업을 안전하게 구체화할 수 있다면 질문 없음이라고 작성한다.

## 완료 조건

구현 완료 여부를 사람이 명확하게 판단할 수 있는 조건을 작성한다.

각 조건은 가능하면 다음과 같이 통과 또는 실패를 판정할 수 있어야 한다.

- 사용자가 수행할 수 있는 동작
- API 응답
- 화면 상태
- 오류 처리
- 권한 처리
- 데이터 저장 결과
- 테스트 결과

“정상적으로 동작한다”처럼 검증 기준이 불분명한 표현만 사용하지 않는다.

## 테스트 계획

이번 변경을 검증하기 위해 필요한 테스트를 작성한다.

해당되는 경우 다음 테스트를 포함한다.

- 단위 테스트
- React 컴포넌트 테스트
- Spring Boot API 테스트
- 서비스 테스트
- PostgreSQL 통합 테스트
- 권한 테스트
- 회귀 테스트
- 브라우저 E2E 테스트
- 수동 확인 항목

정상 상황뿐 아니라 오류와 예외 상황도 포함한다.

## 위험요소

이번 작업으로 발생할 수 있는 다음 위험을 작성한다.

- 기존 기능의 회귀
- API 호환성 문제
- 데이터 손상 또는 유실
- 권한 누락
- 성능 저하
- 동시성 문제
- 테스트되지 않은 조건
- 현재 정보만으로 확인할 수 없는 부분

확인된 문제와 가능성이 있는 위험을 구분한다.

## 제안 작업 단계

작업을 작고 검토 가능한 순서로 나눈다.

각 단계는 가능하면 다음 조건을 만족해야 한다.

- 하나의 명확한 목적이 있다.
- 변경 범위가 작다.
- 독립적으로 검증할 수 있다.
- 실패했을 때 쉽게 되돌릴 수 있다.
- 앞 단계와 뒤 단계의 의존관계가 명확하다.

# 중단 조건

작업 정의서와 구현 계획을 작성한 후 작업을 중단한다.

사용자가 계획을 명시적으로 승인하기 전에는 다음 작업을 수행하지 않는다.

- 소스코드 수정
- 파일 생성 또는 삭제
- 데이터베이스 Migration 작성
- 새로운 의존성 추가
- 테스트 코드 수정
- 설정 파일 수정
- Commit 또는 Push

최종 응답에는 아직 코드를 수정하지 않았다는 사실을 명확하게 표시한다.

 

 

사용 예시

$feature-clarifier

사용자 목록 화면에 검색 조건 저장 기능을 추가하려고 한다.

현재 저장소를 확인하고 다음 작업을 수행해라.

- 아직 코드는 수정하지 않는다.
- 현재 검색 조건이 어디에서 관리되는지 확인한다.
- 기존에 비슷한 기능이 있는지 찾는다.
- 이번 작업의 포함 범위와 제외 범위를 구분한다.
- 확인된 사실과 가정을 구분한다.
- 완료 조건과 테스트 계획을 작성한다.
- 작업을 작고 검토 가능한 단계로 나눈다.

 

이 Skill을 사용하면 '대충 알아서 만들어줘'라는 요청이 바로 수십 개 파일 수정으로 이어지는 것을 막을 수 있다.