# skillDesk 문서 확장 설계

## 목표

현재 프로젝트의 10개 스킬 문서를 원문에 더 가깝게 확장하고, 사용자가 바로 이해하고 검증할 수 있도록 루트 README와 TRAE 실사용 테스트 시나리오 문서를 추가한다.

## 범위

이번 작업은 다음 세 가지를 포함한다.

1. `.trae/skills/*/SKILL.md` 10개 문서 확장
2. 루트 `README.md` 신규 작성
3. `docs/test-scenarios.md` 신규 작성

이번 작업은 다음을 포함하지 않는다.

- 실제 스킬 실행 엔진 개발
- 자동 테스트 실행 스크립트 작성
- 외부 설치 자동화
- Git 커밋 자동 생성

## 현재 상태

- 루트에는 [skillText.md](file:///Users/woozooni/Documents/trae_projects/skillDesk/skillText.md) 가 있고, 10개 스킬 목록의 한국어 번역이 있다.
- `.trae/skills/` 아래에 10개 스킬 디렉터리와 `SKILL.md`가 생성되어 있다.
- 현재 스킬 문서는 핵심 요약형에 가깝고, 원문 세부 규칙과 절차 복원 수준은 낮다.
- 루트 `README.md`는 아직 없다.
- 테스트 시나리오 문서도 아직 없다.

## 설계 방향

### 1. 스킬 문서 확장

각 `SKILL.md`는 현재의 짧은 요약형에서 벗어나, 원문에 더 가까운 아래 구조를 갖는다.

- 언제 사용하는지
- 반드시 지켜야 하는 규칙
- 단계별 작업 흐름
- 권장/비권장 행동
- 결과물 기대치
- 필요 시 예시 프롬프트 또는 운영 팁

모든 스킬을 원문 그대로 기계 번역하는 방식은 피한다. 대신 다음 원칙을 따른다.

- 원문 핵심 규칙, 체크리스트, 금지 사항은 최대한 보존한다.
- 한국어 사용성과 현재 프로젝트 맥락을 고려해 불필요한 외부 의존 서술은 줄인다.
- 지나치게 긴 원문은 구조화해서 읽기 쉽게 재편집한다.
- frontmatter `description`은 짧고 명확하게 유지한다.

### 2. README 구조

루트 `README.md`는 프로젝트 안내문 역할을 하며 아래 내용을 포함한다.

- 프로젝트 소개
- 포함된 10개 스킬 목록
- 디렉터리 구조 설명
- TRAE에서 사용하는 방법
- 추천 사용 흐름
- 문서 확장 기준 설명
- 테스트 시나리오 문서 위치 안내

README는 "이 저장소가 무엇인지, 어떻게 써야 하는지"를 처음 보는 사람도 바로 이해할 수 있게 작성한다.

### 3. 테스트 시나리오 문서

`docs/test-scenarios.md`는 실제 TRAE에서 복붙 가능한 검증 시나리오 모음으로 작성한다.

각 시나리오는 아래 형식을 따른다.

- 시나리오 목적
- 사전 조건
- 입력 프롬프트
- 기대 동작
- 확인 포인트

10개 스킬 각각 최소 1개 이상의 대표 시나리오를 둔다. 필요하면 공통 시나리오도 추가한다.

## 정보 구조

### 스킬 문서 일관성 규칙

모든 `SKILL.md`는 아래 섹션 순서를 가능한 한 맞춘다.

1. 개요
2. 언제 사용할지
3. 핵심 규칙
4. 단계 또는 워크플로
5. 금지 사항 또는 안티 패턴
6. 기대 결과
7. 예시 또는 운영 팁

스킬마다 성격이 다르므로 완전히 동일한 틀을 강제하지는 않지만, 사용자 관점에서 탐색성이 유지되도록 한다.

### README와 테스트 문서 연결

- README에서 테스트 시나리오 문서를 직접 링크한다.
- README에서 스킬별 문서 위치도 빠르게 찾을 수 있게 정리한다.
- 테스트 문서에서는 각 스킬 파일명을 명시해 사용자가 대응 관계를 이해할 수 있게 한다.

## 구현 단위

### 단위 A: 기존 스킬 문서 확장

대상 파일:

- `.trae/skills/brainstorming/SKILL.md`
- `.trae/skills/frontend-design/SKILL.md`
- `.trae/skills/ui-ux-pro-max/SKILL.md`
- `.trae/skills/systematic-debugging/SKILL.md`
- `.trae/skills/writing-plans/SKILL.md`
- `.trae/skills/find-skills/SKILL.md`
- `.trae/skills/using-superpowers/SKILL.md`
- `.trae/skills/karpathy-guidelines/SKILL.md`
- `.trae/skills/webapp-testing/SKILL.md`
- `.trae/skills/agent-browser/SKILL.md`

접근 방식:

- 이미 있는 한국어 문서를 기반으로 구조를 넓힌다.
- 원문에서 확인한 사용 시점, 워크플로, 금지 사항을 최대한 반영한다.
- 서로 중복되는 규칙은 표현은 달리하되 의미를 맞춘다.

### 단위 B: README 작성

대상 파일:

- `README.md`

접근 방식:

- 저장소 소개에서 시작해 사용 흐름으로 내려가는 구조를 사용한다.
- 표 또는 목록으로 10개 스킬을 빠르게 훑을 수 있게 한다.
- 문서 탐색 링크를 충분히 제공한다.

### 단위 C: 테스트 시나리오 작성

대상 파일:

- `docs/test-scenarios.md`

접근 방식:

- 각 스킬당 1개 이상 총 10개 이상의 대표 프롬프트를 작성한다.
- 실제 TRAE 사용자가 바로 실행할 수 있는 형태로 구체화한다.
- 기대 결과를 너무 추상적으로 쓰지 않고, 어떤 종류의 응답이 나와야 하는지 명시한다.

## 품질 기준

완료 판단 기준은 다음과 같다.

- 10개 스킬 문서가 현재보다 명확히 더 상세해진다.
- README만 읽어도 프로젝트 구조와 사용법을 이해할 수 있다.
- 테스트 시나리오 문서만으로 실제 검증을 시작할 수 있다.
- 문서 간 링크와 역할 분담이 자연스럽다.
- Markdown 진단 오류가 없다.

## 리스크와 대응

### 리스크 1: 문서가 과도하게 길어짐

대응:

- 핵심 규칙은 유지하되, 반복 표현은 줄인다.
- 표와 목록을 적극 사용한다.

### 리스크 2: 원문 충실도와 한국어 가독성 충돌

대응:

- 규칙과 단계는 원문에 가깝게 유지한다.
- 설명 문장은 한국어 사용성을 우선해 재구성한다.

### 리스크 3: 테스트 시나리오가 추상적이 됨

대응:

- 실제 입력 프롬프트를 그대로 넣는다.
- 기대 응답의 구조와 체크 포인트를 함께 적는다.

## 검증 계획

- 수정 후 각 Markdown 파일에 대해 진단을 확인한다.
- README, 테스트 문서, 스킬 문서 간 링크와 명칭 일관성을 점검한다.
- 시나리오가 실제 스킬 설명과 어긋나지 않는지 교차 검토한다.

## 최종 산출물

- 확장된 10개 `SKILL.md`
- 루트 `README.md`
- `docs/test-scenarios.md`
