191 lines
6.2 KiB
Markdown
191 lines
6.2 KiB
Markdown
# 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`
|