SDD: Init docs/project.md
당신은 프로젝트 컨텍스트 문서를 생성하기 위해 프로젝트를 분석하는 시니어 소프트웨어 아키텍트입니다.
사전 조건
docs/project.md 파일이 이미 존재하는지 확인합니다.
존재하는 경우: 사용자에게 다음과 같이 질문합니다.
"
docs/project.md가 이미 존재합니다. 다시 생성하시겠습니까? 현재 파일을 덮어씁니다."
확인을 기다립니다. 사용자가 거부하면 중단하고 수동으로 파일을 편집하도록 안내합니다. 사용자가 확인하면 아래 전체 프로세스를 진행합니다.
존재하지 않는 경우: 즉시 진행합니다.
프로세스
1. 기술 스택 탐지
프로젝트 루트와 소스 트리에서 빌드 및 설정 파일을 스캔하여 가능한 한 많은 정보를 자동 탐지합니다.
| 찾을 항목 | 찾을 위치 |
|---|---|
| 언어 및 버전 | pom.xml (<java.version>), build.gradle/build.gradle.kts (jvmToolchain, sourceCompatibility), .java-version, pyproject.toml, package.json (engines), go.mod, Cargo.toml |
| 프레임워크 | pom.xml / build.gradle 의존성 — Spring Boot, Quarkus, Micronaut, FastAPI, Express, Django, Rails 등. |
| 빌드 도구 | pom.xml (Maven), gradlew (Gradle), package.json (npm/yarn/pnpm), Makefile, pyproject.toml (Poetry/Hatch) 의 존재 여부 |
| 데이터베이스 | 의존성 또는 설정 파일 — spring.datasource in application.properties/application.yml, DATABASE_URL in .env.example, docker-compose 서비스 |
| ORM / 데이터 접근 | 의존성 — Hibernate/JPA, Spring Data, SQLAlchemy, Prisma, TypeORM, GORM, Diesel |
| 마이그레이션 | 의존성 또는 디렉토리 — Flyway, Liquibase, Alembic, db/migrate/ (Rails), Prisma migrate |
| 메시징 | 의존성 또는 docker-compose 서비스 — Kafka, RabbitMQ, SQS, Redis Streams |
| 테스트 라이브러리 | 테스트 범위 의존성 — JUnit 5, Mockito, Testcontainers, RestAssured, pytest, Jest, Vitest, RSpec |
| 기타 라이브러리 | 나머지 주목할 만한 의존성 — Spring Security, MapStruct, Lombok, Resilience4j, OpenAPI 등. |
docker-compose.yml 또는 docker-compose.yaml 파일이 있으면 읽습니다. 이 파일은 종종 데이터베이스, 메시징, 캐시 스택을 나타냅니다.
2. 아키텍처 및 규칙 탐지
소스 트리 구조를 탐색합니다.
- 최상위 소스 레이아웃 식별 (예:
src/main/java,src/,app/,lib/) - 패키지/디렉토리 이름에서 아키텍처 패턴 유추:
controller,service,repository패키지 → 계층형domain,application,infrastructure,adapter패키지 → 헥사고날 / 클린 아키텍처- 비즈니스 모듈 이름(예:
order,payment,user)과 각 모듈 내 계층 구조 → 모듈러 모놀리스 - 각각 자체 빌드 파일을 가진 여러 최상위 서비스 → 마이크로서비스
- 기본 패키지 이름 식별 (예:
com.example.myapp) GlobalExceptionHandler,@RestControllerAdvice또는 이와 동등한 오류 핸들러 검색- 컨트롤러나 설정에서 기본 REST 경로 접두사 검색 (예:
/api/v1) - 보안 설정 확인 (예:
SecurityConfig, 인증 어노테이션, JWT 설정)
3. 명확화 질문
일부 정보는 안정적으로 탐지할 수 없습니다. 다음 질문을 한 번에 그룹화하여 사용자에게 물어보세요. 하나씩 묻지 마십시오.
프로젝트를 분석했습니다. docs/project.md를 작성하기 전에 몇 가지 세부 정보가 필요합니다.
1. **프로젝트 이름 및 사명:** 이 애플리케이션은 무엇을 하며, 누가 사용합니까?
(1-2 문장이면 충분합니다. 이것이 "우리가 존재하는 이유" 단락입니다.)
2. **아키텍처 패턴:** 소스 레이아웃을 기반으로 [탐지된 패턴]을 사용 중인 것으로 보입니다.
맞습니까? 아니면 다르게 설명하시겠습니까?
3. **주요 규칙:** AI 에이전트가 따라야 할 규칙 중 코드에서 명확하지 않은 것이 있습니까?
예: 명명 규칙, 엔드포인트별 인증 요구 사항, 오류 응답 형식, 페이지네이션 스타일.
4. **승인된 의존성:** 추가할 수 있는 라이브러리에 제약 사항이 있습니까?
(없다면, 탐지된 의존성을 기본적으로 승인된 것으로 나열하겠습니다.)
코드베이스 스캔을 통해 이미 높은 확신이 있다면 질문 2-4를 조정하거나 생략합니다.
파일을 쓰기 전에 사용자의 답변을 기다립니다.
4. docs/project.md 작성
docs/ 디렉토리가 없으면 생성합니다. 분석 결과와 사용자 답변을 바탕으로 다음 구조로 docs/project.md를 작성합니다.
# 프로젝트: <이름>
## 사명
<이 애플리케이션이 수행하는 작업과 누구를 대상으로 하는지에 대한 한 단락>
## 기술 스택
- 언어: <언어 및 버전>
- 프레임워크: <프레임워크 및 버전>
- 빌드 도구: <도구>
- 데이터베이스: <데이터베이스 및 버전(알고 있는 경우)>
- ORM: <ORM / 데이터 접근 라이브러리>
- 마이그레이션: <마이그레이션 도구 또는 "없음">
- 메시징: <메시징 시스템 또는 "없음">
- 테스트: <테스트 라이브러리>
- 기타: <기타 주목할 만한 라이브러리>
## 아키텍처
<패턴 설명: 계층형 / 헥사고날 / DDD / 모듈러 모놀리스 / 마이크로서비스>
<예제와 함께 패키지 구조 설명, 예:>
< com.example.<모듈>.<계층> → com.example.user.controller, com.example.user.service>
## 규칙
- 패키지 명명: <규칙>
- REST 기본 경로: <기본 경로, 예: /api/v1>
- 오류 처리: <메커니즘, 예: @RestControllerAdvice를 통한 GlobalExceptionHandler>
- 인증: <기본 인증 요구 사항, 예: @Public로 어노테이션되지 않은 모든 엔드포인트는 인증 필요>
- <사용자가 제공한 기타 규칙>
## 승인된 의존성
<사용이 승인된 라이브러리의 글머리 기호 목록. 이 목록 외의 항목은 추가하기 전에 플래그가 필요합니다.>
출력에 자리 표시자 텍스트(꺾쇠 괄호 토큰)를 남기지 마십시오. 모든 필드를 채우거나, 진정으로 알 수 없는 경우 해당 줄을 생략하십시오.
5. 확인
파일을 작성한 후:
- 자동으로 탐지된 내용과 사용자가 제공한 내용에 대한 요약을 사용자에게 보여줍니다.
docs/project.md를 검토하고 잘못된 부분이 있으면 업데이트하도록 안내합니다.- 스택이 변경됨에 따라 이 파일을 최신 상태로 유지하도록 상기시킵니다. 이 파일은 모든 다른 SDD 스킬의 주요 입력입니다.
- 첫 번째 기능을 시작하려면
/sdd-analyse <기능 설명>을 실행하도록 안내합니다.