zhichao1208/better-doc

Better Doc

두 가지 상호 보완적인 프레임워크를 사용하여 문서를 검토하세요:

• 고전 스타일 (핑커) - 명확성, 정밀성, 필요성
• 스마트 브레비티 (Axios) - 구조, 스캔 가능성, 영향력

목표: 텍스트를 의미로 향하는 투명한 창문으로 만듭니다. 간결함은 자신감, 장황함은 두려움입니다.

핵심 규칙: 내용 보존

간결함 ≠ 삭제. 표현을 단순화하고 의미를 보존하세요.

특히 프롬프트와 같은 기존 문서를 검토할 때:

해야 할 일	하지 말아야 할 일
장황한 요구사항을 더 직접적으로 만듭니다	긴 것 같다고 요구사항을 삭제합니다
장황한 설명을 압축합니다	독자가 필요한 맥락을 제거합니다
모호한 용어를 구체적인 용어로 대체합니다	제약 조건이나 엣지 케이스를 제거합니다
명확성을 위해 재구성합니다	재구성하면서 정보를 잃습니다

무언가를 자르기 전에 다음을 물어보세요:

1. 이것이 요구사항, 제약 조건 또는 맥락을 전달하는가?
2. 이것을 제거하면 결과가 달라지는가?
3. 삭제하는 대신 더 적은 단어로 같은 것을 말할 수 있는가?

특히 프롬프트의 경우:

• 문단에 묻힌 요구사항 → 명시적인 불릿 포인트로 추출
• 암시적 제약 조건 → 명시적으로 만들고, 당연하다고 가정하지 않음
• 장황한 맥락 → 압축하되, 동작에 영향을 미친다면 유지
• 예시 → 엣지 케이스를 명확히 하면 유지, 중복되면 제거

잘못된 접근: "이 문단이 길어서 삭제합니다." 올바른 접근: "이 문단에 3개의 요구사항이 있습니다. 3개의 불릿 포인트로 다시 작성하세요."

핵심 원칙

고전 스타일 (8가지 원칙)

1. 직접적인 언어 - 능동태, 명확한 행위자
2. 필요한 내용만 - 이해를 향상시키지 않는 것은 제거
3. 인위적인 복잡성 없음 - 구조는 명확성을 위한 수단, 장식이 아님
4. 추상보다는 구체적으로 - 구체적이고 검증 가능한 용어
5. 일관된 용어 - 개념 하나에 이름 하나
6. 명확한 의도 - 목표, 제약 조건, 출력 형식 (프롬프트의 경우)
7. 독자 우선 순서 - 이해 경로를 따르는 순서
8. 검증 가능한 주장 - 인상이 아닌 사실과 논리

스마트 브레비티 (4가지 구성요소)

1. 강력한 헤드라인 - 6단어 이하, 주목을 끌기
2. 하나의 핵심 - 첫 문장 = 기억해야 할 한 가지
3. 중요한 이유 - 독자와의 관련성에 대한 맥락
4. 더 깊이 알아보기 - 선택적 세부 정보, 불릿으로 덩어리화

자세한 설명: references/principles.md

검토 워크플로

1단계: 문서 분류

유형	초점 영역
이메일/업데이트	스마트 브레비티 구조, 스캔 가능성
프롬프트/지침	의도 명확성, 제약 조건, 형식
기술 문서	정밀성, 용어, 계층 구조
일반 텍스트	고전 스타일, 흐름, 필요성

2단계: 스마트 브레비티 구조 확인

이메일, 업데이트, 공지의 경우:

✓ 헤드라인: 6단어 이하의 강력한 단어?
✓ 첫 문장: 하나의 핵심 메시지?
✓ "중요한 이유": 독자 관련성이 명확한가?
✓ 세부 정보: 불릿으로 스캔 가능한가?
✓ 굵게: 핵심 용어가 강조되었는가?

3단계: 고전 스타일 확인

원칙	위험 신호
직접적인 언어	수동태, 명사화, 묻힌 동사
필요한 내용	잉여, 반복, 당연한 진술
복잡성 없음	과도한 서식, 중첩 불릿, 불필요한 헤더
구체적	"다양한", "측면", 정의되지 않은 전문 용어
일관된 용어	같은 것, 다른 이름
명확한 의도	목표 누락, 모호한 제약 조건
독자 순서	주제 점프, 맥락보다 먼저 결론
검증 가능	"그렇게 보입니다", 뒷받침되지 않은 주장

4단계: 단어 수준 문제 확인

스마트 브레비티 단어 규칙:

• 짧은 단어 승리: 1음절 > 2음절 > 3음절
• 제거: 부사, 약한 단어, 얼버무리는 단어
• 항상 능동 동사 사용

제거 대상	유지/대체 대상
"~하기 위하여"	"~하려면"
"~라는 사실 때문에"	"~이므로"
"현 시점에서"	"지금"
"활용하다"	"사용하다"
"구현하다"	"하다" / "만들다"
"용이하게 하다"	"돕다" / "가능하게 하다"

5단계: 결과 보고

## 검토 요약

**유형**: [email/prompt/technical/general]
**전반적**: [한 줄 평가]

## 구조 (스마트 브레비티)
- 헤드라인: [✓/✗ + 수정]
- 첫 문장: [✓/✗ + 수정]
- 중요한 이유: [✓/✗ + 수정]
- 스캔 가능성: [✓/✗ + 수정]

## 스타일 (고전)
[위반 사항을 위치, 문제, 수정과 함께 나열]

## 제안된 수정
[요청 시 개선된 버전]

빠른 참조: 스마트 브레비티 형식

이메일 및 업데이트의 경우 다음 구조를 사용하세요:

**[6단어 헤드라인]**

[한 문장: 핵심 메시지]

**중요한 이유**: [독자 관련성에 대한 1-2 문장]

**다음 단계** / **더 깊이 알아보기** / **세부 정보**:
• [불릿 1]
• [불릿 2]
• [불릿 3]

**결론**: [선택적 마무리 메시지]

프롬프트별 확인 사항

대상 구조:

목표: [명확한 단일 진술]

제약 조건:
- [경계 1]
- [하지 말아야 할 것]
- [길이/형식 제한]

출력 형식: [정확한 구조]

기존 프롬프트 개선 시:

원래 문제	수정 (삭제하지 않음)
산문에 묻힌 요구사항	추출 → 명시적 불릿
모호한 제약 조건 ("주의하세요")	구체적으로 만들기 ("절대 X를 초과하지 마세요")
암시적 가정	명시적으로 진술
중복 예시	다른 예시가 다루는 경우에만 제거
엣지 케이스에 대한 긴 설명	압축하되, 규칙은 유지

최종 확정 전 체크리스트:

• 모든 원래 요구사항이 여전히 존재하는가?
• 제약 조건이 이전보다 더 명시적인가?
• 재구성 과정에서 잃은 것이 없는가?
• 더 짧아지고 AND 더 명확해졌는가? (단순히 더 짧아진 것이 아닌가?)

경고: 목표 누락, 모호한 용어 ("좋은", "적절한"), 출력 형식 없음.

일반적인 수정 사항

문제	전	후
수동태	"데이터가 처리됩니다"	"시스템이 데이터를 처리합니다"
명사화	"결정을 내리다"	"결정하다"
잉여 표현	"주목하는 것이 중요합니다"	[삭제]
긴 단어	"활용하다"	"사용하다"
모호함	"다양한 요인"	"비용, 시간, 범위"
약한 헤드라인	"프로젝트 업데이트"	"프로젝트, 금요일 출시"
묻힌 핵심	[요점 앞에 문단]	[요점 먼저]

---

관련 스킬

신뢰할 수 있고 명확한 커뮤니케이션을 위한 소규모 오픈 에이전트 스킬군의 일부입니다:

• reduce-hallucination — LLM 에이전트 감사; 근거 제시, 인용, 기권.
• better-doc — 고전 스타일 + 스마트 브레비티.
• numbers — 숫자를 의미 있게 만들고 깔끔하게 표시합니다.