기능 설계 제안

Propose Feature Design Skill

목적

구현을 안내하는 기술 설계 문서를 만듭니다. 이는 실제 코드를 작성하지 않고 아키텍처, 패턴, 설계 결정 사항을 제공합니다.

사용 시기

• 기능 개념과 요구 사항이 존재할 때
• 구현 접근 방식을 계획할 준비가 되었을 때
• 아키텍처와 설계 패턴을 문서화해야 할 때

전제 조건

• 기능 개념이 docs/features/NNNN-feature-name/concept.md에 존재함
• 요구 사항이 docs/features/NNNN-feature-name/requirements.md에 존재함
• 사용자가 기술 접근 방식을 이해함

절차

1. 전제 조건 확인

# 개념과 요구 사항이 있는지 확인
ls ./docs/features/NNNN-feature-name/concept.md
ls ./docs/features/NNNN-feature-name/requirements.md

둘 중 하나라도 없으면 해당 단계를 먼저 완료하세요.

2. 아이디어 다듬기 문서 확인

ls ./planning/NNNN-feature-name/idea-honing.md 2>/dev/null

존재한다면, 아이디어 다듬기 중 논의된 설계 인사이트와 기술적 고려 사항을 검토하세요.

3. 설계 템플릿 복사

cp ./docs/features/0000-templates/design.md ./docs/features/NNNN-feature-name/

4. 개요 작성

아키텍처와 설계 접근 방식에 대한 높은 수준의 설명을 작성합니다. 개념과 요구 사항을 참조하세요.

5. 중요 제약 조건 식별

각 주요 작업에 대해 다음을 질문하세요:

• 이것을 구현하는 잘못된 방법은 무엇인가?
• 어떤 성능 특성이 필요한가?
• 어떤 불변 조건이 유지되어야 하는가?

중요 제약 조건 표를 다음으로 채우세요:

• ID: CC-1, CC-2 등
• 제약 조건: 반드시 특정 방식으로 수행되어야 하는 것
• 근거: 이유 (성능, 정확성, 보안)
• 안티 패턴: 리뷰에서 거부해야 할 잘못된 접근 방식

이것은 구현 실수를 방지하는 가장 중요한 섹션입니다. 구체적으로 작성하세요—모호한 제약 조건은 도움이 되지 않습니다.

6. 아키텍처 정의

전체 구조를 설명하세요:

• 컴포넌트 관계
• 데이터 흐름
• 계층별 책임
• 통합 지점

필요한 경우 ASCII 아트를 사용한 간단한 다이어그램을 사용하세요.

7. 솔루션 메커니즘 설명

이 섹션은 '왜'(개념)와 '무엇'(아키텍처)을 연결합니다. 개념에서 식별된 각 핵심 과제에 대해 설계가 어떻게 이를 해결하는지 설명하세요.

각 과제에 대해 다음을 답하세요:

• 근본적인 문제는 무엇인가? (concept.md에서)
• 어떤 아키텍처 요소가 이를 해결하는가?
• 왜 이 접근 방식이 작동하는가?
• 다르게 했을 때 무엇이 실패할 것인가?

표 또는 구조화된 목록 형식:

과제	아키텍처 요소	작동 이유
개념의 과제	이를 해결하는 컴포넌트/패턴	메커니즘 설명

작성자를 위한 프롬프트:

• "누군가 '이것이 어떻게 X를 해결하나요?'라고 물었을 때, 특정 컴포넌트를 가리킬 수 있나요?"
• "새로운 엔지니어가 왜 이 설계가 대안보다 선택되었는지 이해할 수 있나요?"
• "각 주요 컴포넌트가 문제와 연결된 명확한 존재 이유를 가지고 있나요?"

이 섹션은 리뷰어가 설계가 단지 그럴듯한 코드 구조를 설명하는 것이 아니라 실제로 명시된 문제를 해결한다는 확신을 갖게 해야 합니다.

8. 도메인 모델 정의

핵심 유형과 작업을 명세하세요:

유형

• 목적과 역할
• 주요 속성
• 유효성 검사 규칙
• 다른 유형과의 관계

작업

• 함수 시그니처 (개념적)
• 수행하는 작업
• 주요 동작
• 불변 조건 (항상 참이어야 하는 것)

9. 모듈 구조 정의

코드가 어떻게 구성되어야 하는지 보여주세요:

• 디렉터리 구조
• 모듈 책임
• 파일 조직
• 관심사 분리

모듈 크기 제한: 이 프로젝트는 모듈당 550줄 제한을 적용합니다 (scripts/lint_loc.py 참조). 모듈을 설계할 때 컴포넌트가 이 제한을 초과할 수 있는지 고려하세요. 초과할 경우 내부 분해를 사전에 계획하세요—아티팩트 유형별이 아니라 기능별로 분할하세요(예: builder.rs, searcher.rs). 린터의 출력에는 제한을 초과할 경우 리팩터링 지침이 포함됩니다.

impl 블록을 함께 유지: 한 유형에 대한 모든 impl 블록은 하나의 파일에 있어야 합니다. impl 블록을 여러 파일에 흩뜨리면 독자(및 AI)가 유형이 수행하는 작업의 전체 그림을 얻기 어렵습니다. 유형의 구현이 너무 큰 경우, impl 블록 자체를 분할하지 말고 헬퍼 함수나 내부 컴포넌트 유형에 위임하세요.

// ✅ 좋음: 단일 impl 블록이 헬퍼에 위임
impl KnowledgeIndex {
    pub fn build(&self, path: &Path) -> Result<()> {
        self.builder.build(path)  // 내부 컴포넌트에 위임
    }
}

// ❌ 나쁨: impl 블록이 여러 파일에 분할됨
// facade/mod.rs: impl KnowledgeIndex { fn new() ... }
// facade/build.rs: impl KnowledgeIndex { fn build() ... }
// facade/search.rs: impl KnowledgeIndex { fn search() ... }

10. 설계 패턴 문서화

관련 패턴과 적용 이유를 설명하세요:

• 사용할 패턴
• 문제에 어떻게 적합한지
• 구현 지침

11. 설계 결정 사항 문서화

대안 간의 중요한 선택에 대해 설계 결정 사항 섹션에 항목을 추가하세요:

• 결정된 사항
• 고려된 대안
• 이 옵션이 선택된 이유
• 구현에 미치는 영향

이것은 구현자가 추론을 이해하는 데 도움이 되는 기록을 만듭니다.

12. 구현 지침 추가

구현자를 위한 주요 고려 사항:

• 중요 제약 조건을 ID로 참조
• 성능 고려 사항
• 테스트 접근 방식
• 처리해야 할 엣지 케이스

13. 코드 최소화 유지

기억하세요:

• 최소한의 설명 코드 사용
• 아키텍처와 결정 사항에 초점
• 구현자를 안내하고, 구현하지 마세요
• 관련 시 요구 사항을 ID로 참조

검증

설계 문서를 확인하세요:

# 파일 존재 확인
ls ./docs/features/NNNN-feature-name/design.md

# 내용 확인
head -50 ./docs/features/NNNN-feature-name/design.md

일반적인 문제

코드가 너무 많음: 큰 코드 블록이 있으면 제거하고 지침에 집중하세요.

너무 추상적: 설계가 모호하면 구체적인 유형 이름과 모듈 구조를 추가하세요.

아키텍처 누락: 세부 사항에 들어가기 전에 전체 구조가 명확한지 확인하세요.

요구 사항을 참조하지 않음: 설계 결정을 특정 요구 사항 ID와 연결하세요.

솔루션 메커니즘 누락: 설계가 구조를 설명하지만 문제를 해결하는 이유를 설명하지 않으면, 과제를 아키텍처 요소에 매핑하는 솔루션 메커니즘 섹션을 추가하세요.

다음 단계

설계를 만든 후:

1. 구현자와 함께 타당성 검토
2. 피드백에 따라 개선
3. 설계가 확정되면 propose-feature-test-plan 스킬을 사용하여 테스트 계획 생성
4. 그런 다음 propose-implementation-plan 스킬을 사용하여 구현 계획 생성