---
name: tech-spec
description: >
  기능·시스템 아이디어를 구현 가능한 TechSpec으로 작성하거나 기존 기술 명세를 개선할
  때 로드한다. 목표, 비목표, 설계, 대안, 리스크, 검증 방법과 미결 사항을 정리한다.
---

# TechSpec 작성

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

## 입력 확인

먼저 다음 정보를 찾는다.

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

입력이 충분하면 바로 초안을 작성한다. 중요한 설계 결정을 바꿀 정보가 빠졌을 때만
한 번에 1~3개의 구체적인 질문을 한다. 답을 몰라도 진행할 수 있는 내용은 합리적인
가정으로 표시하고 `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으로 제공한다.

## 문장

명세는 구현자가 그대로 따라 만드는 문서라서 AI 티가 곧 모호함이 된다. 아래를 거른다.

- "효율적인", "원활한", "다양한", "강력한", "적절한", "유연한" 같은 만능 수식어를 쓰지
  않는다. 어떤 값·동작·조건인지 적는다.
- "개선", "강화", "최적화", "고도화", "안정화"는 무엇을 어떻게 바꾸는지로 푼다.
  "성능 개선" → "p99 응답을 800ms 에서 300ms 로".
- "~할 수 있다"를 남발하지 않는다. 설계가 그렇게 동작하면 "~한다", 선택 사항이면 조건을
  붙여 "~이면 ~한다"로 쓴다.
- 확실하지 않은 것은 본문에서 "~것으로 보인다"로 흐리지 않고 `Open Questions`로 보낸다.
  본문은 단정형이다.
- "단순히 A가 아니라 B", "A를 넘어 B로" 대구를 쓰지 않는다. B 를 바로 적는다.
- "-고,", "-며,", "-지만," 연결어미 뒤에 쉼표를 찍지 않는다. 길면 문장을 나눈다.
- "~에 대해", "~에 있어", "~와 관련하여", "~를 통해"(문단 3회 이상), "~에 의해 ~된다"
  같은 번역투를 우리말 조사와 능동으로 바꾼다. "-성/-화/-적" 명사화 체인("확장성의 확보를
  위한 구조적 개선")은 동사로 푼다("확장하기 쉽게 구조를 바꾼다").
- 문두 "또한", "따라서", "즉", "이는 ~"를 반복하지 않는다.
- "결론적으로", "다음과 같은", "크게 세 가지로" 도입·결산 문구, 이모지, 본문 볼드, "X: Y"
  콜론 부제 헤딩을 쓰지 않는다. 템플릿의 섹션 제목과 표는 구조라서 예외다.
- API·토큰·큐·롤백 같은 표준 기술 용어는 원어로 둔다.

전체 패턴 목록과 전후 예시는 이 저장소의
`plugins/workspace/skills/korean-humanize/ai-tell-catalog.md` 가 source 다. 인라인 규칙과
카탈로그가 어긋나면 카탈로그가 이긴다.