---
name: tech-spec
description: >
  기능·시스템의 기술 명세, TechSpec·RFC·설계안을 작성하거나 개선할 때 쓴다.
  목표·설계·대안·실패 경로와 검증 기준을 정리해 구현과 검토에 필요한 결정을 드러낸다.
---

# TechSpec 작성

요구사항을 구현자가 의사결정과 검증에 바로 사용할 수 있는 기술 명세로 바꾼다.

ISO 24495-1처럼 쉽게 찾고 이해하고 사용할 수 있게, ASD-STE100처럼 짧고 명확하며
모호하지 않게 쓴다. 독자에게 필요한 결정·조건·검증을 제목으로 구분하고 같은 개념에는
같은 용어를 쓴다. 낯선 약어는 처음에 풀어 쓴다. 영어 전용 어휘·단어 수 규칙은 한국어에 강제하지 않는다.

## 입력 확인

먼저 다음 정보를 찾는다.

- 해결하려는 문제와 대상 사용자
- 현재 동작과 원하는 동작
- 성공 기준
- 기술·일정·호환성 제약
- 영향을 받는 시스템과 외부 의존성

입력이 충분하면 바로 초안을 작성한다. 중요한 설계 결정을 바꿀 정보가 빠졌을 때만
필요한 질문을 묶어 확인한다. 답을 몰라도 진행할 수 있는 내용은 합리적인
가정으로 표시하고 `Open Questions`에 남긴다.

## 설계 검토

다음 순서로 판단한다.

1. 문제와 해결책을 분리한다.
2. 요청한 범위와 명시적인 non-goals를 정한다.
3. 가장 단순한 구현안을 기본안으로 선택한다.
4. 실제로 고려할 가치가 있는 대안만 비교한다.
5. 데이터 흐름, 상태 변화, 실패 경로와 호환성을 확인한다.
6. 보안, 개인정보, 비용, 운영과 롤백 위험을 검토한다.
7. 각 단계에 검증 가능한 완료 조건을 붙인다.

근거 없는 기술 선택을 만들지 않는다. 저장소·API·조직 관례를 제공받지 못했다면
특정 구조가 이미 존재한다고 단정하지 않는다.

## 출력 형식

요청 맥락에 맞게 불필요한 섹션은 생략하되, 다음 구조를 기본으로 사용한다.

```markdown
# [기능명] TechSpec

## Summary
[문제, 제안, 기대 효과를 짧게 설명]

## Background
[현재 상태와 이 작업이 필요한 이유]

## Goals
- [측정 가능한 목표]

## Non-goals
- [이번 범위에서 다루지 않는 것]

## Proposed Design
[구성 요소, 책임, 데이터 흐름, 상태 변화]

## Alternatives
| 대안 | 장점 | 단점 | 결정 |
|---|---|---|---|

## Failure Handling
- [실패 조건과 처리]

## Security and Privacy
- [관련 위험과 대응, 해당 없으면 생략]

## Rollout and Rollback
- [배포 순서, 호환성, 관측, 롤백]

## Verification
- [테스트·측정 가능한 완료 조건]

## Milestones
1. [독립적으로 검증 가능한 단계]

## Open Questions
- [ ] [결정이 필요한 항목]
```

## 품질 기준

- 요구사항을 구현 세부사항으로 둔갑시키지 않는다.
- 목표와 검증 방법을 대응시킨다.
- 실패 처리에 “적절히 처리” 같은 모호한 표현을 쓰지 않는다.
- 대안은 기본안과 실질적으로 다른 선택지만 포함한다.
- 일정이나 수치를 근거 없이 만들어내지 않는다.
- 기본은 복사 가능한 Markdown이다. 파일로 전달할 요청이면 `SaveFile`이 있을 때
  Markdown을 저장하고 실제 결과만 전달한다. DOCX·PDF 같은 형식은 연결된
  `document-authoring`과 `File`로 처리하며 도구가 없으면 본문과 미수행 범위를 알린다.

## 독자 테스트

구성 요소가 여러 개이거나 배포·권한·데이터 변경이 걸린 명세는 초안 작성 뒤 독자
관점으로 한 번 더 검사한다.

1. 구현자·리뷰어·운영자가 이 문서만 보고 물을 질문을 5개 안팎으로 만든다.
2. 연결된 서브에이전트로 검토할 수 있으면 초안과 질문을 전달한다.
   없으면 초안을 다시 읽고 문서만으로 답할 수 있는지 자체 점검한다.
3. 질문에 답할 근거가 문서에 있는지, 숨은 전제·모순·정의되지 않은 용어가 있는지 찾는다.
4. 답이 달라질 수 있는 모호함은 해당 섹션을 고치고 다시 질문한다.

새로운 중대한 모호함이 없고 핵심 질문의 답이 문서에서 직접 추적되면 끝낸다. 단순한
짧은 변경 명세에는 이 절차를 강제하지 않는다.

## 문장

구현자가 동작과 조건을 한 가지 뜻으로 해석할 수 있게 쓴다.

- "효율적인", "원활한", "다양한", "강력한", "적절한", "유연한" 같은 만능 수식어를 쓰지
  않는다. 어떤 값·동작·조건인지 적는다.
- "개선", "강화", "최적화", "고도화", "안정화"는 무엇을 어떻게 바꾸는지로 푼다.
  "성능 개선" → "p99 응답을 800ms 에서 300ms 로".
- "~할 수 있다"를 남발하지 않는다. 설계가 그렇게 동작하면 "~한다", 선택 사항이면 조건을
  붙여 "~이면 ~한다"로 쓴다.
- 가정과 미결 결정은 해당 설계 옆에서 표시하고 필요하면 `Open Questions`에 모은다.
  미확정 설계를 현재 보장된 동작처럼 단정하지 않는다.
- 장식적인 대구를 직접 설명으로 바꾼다. 대안·조건·범위의 차이를 설명하는 대조는 유지한다.
- "-고,", "-며,", "-지만," 연결어미 뒤에 쉼표를 찍지 않는다. 길면 문장을 나눈다.
- "~에 대해", "~에 있어", "~와 관련하여", "~를 통해"(문단 3회 이상), "~에 의해 ~된다"
  같은 번역투를 우리말 조사와 능동으로 바꾼다. "-성/-화/-적" 명사화 체인("확장성의 확보를
  위한 구조적 개선")은 동사로 푼다("확장하기 쉽게 구조를 바꾼다").
- 문두 "또한", "따라서", "즉", "이는 ~"를 반복하지 않는다.
- 반복되는 도입·결산 문구와 장식은 줄인다. 제목·목록·강조는 설계와 조건을 찾는 데 필요한 만큼 쓴다.
- API·토큰·큐·롤백 같은 표준 기술 용어는 원어로 둔다.

기본 작성은 위 인라인 규칙으로 충분하다. `korean-humanize`가 현재 연결돼 있고 상세
패턴·예시가 필요할 때만 `Skill(skill_name="korean-humanize", file_path="ai-tell-catalog.md")`로
카탈로그를 읽는다. 연결되지 않았으면 저장소 경로로 찾지 않고 인라인 규칙을 따른다.
카탈로그는 참고 기준이며 사용자 양식·문체와 기술적 의미를 우선한다.