feishu-doc-style은(는) 무엇을 하나요?
Feishu(飞书) 문서 작성 시 지키는 규칙입니다. 기술 설계서, PRD, 회고, 설명 등 모든 문서에 적용됩니다. 목표는 단 하나: 읽는 사람이 한 번에 이해할 수 있도록 하는 것입니다.
사용 시기
Feishu 문서나 기술 문서를 작성, 수정, 검토, 또는 다듬을 때마다 기본적으로 이 규칙을 따릅니다. 사용자가 명시적으로 요청하지 않아도 자동 적용됩니다.
사용자가 /feishu-doc-style을 명시적으로 입력하거나, "이렇게 쓰면 명확한가요?", "이 부분을 어떻게 설명해야 할까요?"라고 물을 때는 "핵심 원칙"과 "제출 전 자가 점검"을 참고하여 수정합니다.
다른 사람의 글을 수정할 때는 먼저 자가 점검 목록을 항목별로 검토하고, 위반 사항을 찾아내어 수정된 작성법을 제시한 후, 무엇을 변경했는지 설명합니다.
핵심 원칙
-
결론만 남기고 추론 과정은 생략합니다. "왜 이렇게 선택했는지", "당시 어떻게 저울질했는지" 같은 유도 과정은 삭제하고 결론만 제시합니다. 독자가 필요한 것은 답이지, 여러분의 사고 과정이 아닙니다.
-
문단은 2-3줄이면 충분합니다. 한 문단은 2-3줄을 넘지 않도록 하고, 여러 문장을 하나의 긴 문단으로 쌓지 마세요. 긴 문단은 읽기 피곤합니다.
-
프로세스 관련 내용은 그림으로 표현하고, 텍스트로 쓰지 않습니다. 무엇이 먼저인지, 데이터가 어떻게 흐르는지, 상태가 어떻게 변하는지 등은 그림으로 표현하고, 긴 텍스트로 설명하지 마세요. 하나의 시퀀스 다이어그램이 긴 텍스트 한 단락보다 훨씬 효과적입니다.
-
화살표는 그림 안에서만 사용합니다. 본문과 표에 'A → B; C → D'와 같은 화살표 속기 체인을 쓰지 마세요. 이런 방식은 독자가 머릿속에서 역추적하게 만들어, 사실상 번역 비용을 독자에게 전가하는 것입니다.
-
쉬운 말로 쓰고, 업계 용어(은어)를 쓰지 않습니다. 내부 용어는 독자가 이해하지 못합니다. 쉬운 말로 바꾸거나, 처음 등장할 때 한 문장으로 설명하세요. 자주 사용되는 은어 대조표는
references/jargon.md를 참조하세요. -
표 셀은 완전한 짧은 문장으로 작성합니다. 셀 안에 용어 약어를 쌓지 말고, '누가 무엇을 했고, 결과가 무엇인지'를 쓰세요.
-
장식용 이모지와 하이라이트 박스를 사용하지 않습니다. 📌 ⭐ 🔒 💡 ✅ 🚧 같은 이모지와 컬러 콜아웃 하이라이트 박스는 페이지를 지저분하고 어수선하게 만듭니다. 강조가 필요하면 '굵은 소제목. 본문' 형식의 일반 문단을 사용하고, 문서 수준의 메모나 상태 알림은
>인용 블록을 사용하세요. 문서 전체에 장식용 이모지나 하이라이트 박스가 하나도 없어야 합니다. -
굵게 강조는 절제합니다. 각 섹션에 최대 한두 군데만, 진정한 전반적인 결론이나 원칙의 머리말에만 굵게 표시합니다. 명사 목록, 필드명, 방향어(왼쪽/가운데/오른쪽)는 절대 굵게 표시하지 않습니다. 계층 구조는 문장과 표 구조로 표현해야지, 화면 전체를 굵게 표시하는 방식으로 표현하지 않습니다.
-
키보드로 입력할 수 없는 문자를 사용하지 않습니다. 동그라미 숫자 ①②③④⑤, 상태 이모지 ✓ ◐ ◑ ● ○, 아이콘처럼 사용하는
!, 기능 아이콘 ⚡ ⌘ 등은 사람이 정상적으로 직접 입력하지 않는 문자이며, UI 텍스트를 그대로 가져온 것처럼 보입니다. 목록은 일반적인 '1. 2. 3.' 순서 목록이나 '첫째, 둘째'를 사용하고, 상태는 '완료됨/진행 중'으로 직접 작성하며, 단계 번호는 일반 숫자(1단계/STEP 1)를 사용하세요. -
제목은 내용을 직접 명시하고, 구조를 쓰지 않습니다. 제목은 해당 섹션이 무엇을 다루는지 직접 말합니다('올해의 목표와 주요 수단', '진행 중인 작업과 진행 상황'). 조직 논리나 작성 프레임워크를 제목에 넣지 마세요. '총:', '분:', '제1부:'와 같은 구조적 접두사를 사용하지 마세요. 총론-분론, 병렬, 선후 관계는 내용 순서와 제목 단계를 통해 자연스럽게 드러납니다. 또한 제목에 메타 설명(AI가 매일 추가하는 것 같은 설명)을 넣지 않습니다. 해당 내용은 본문이나
>인용 블록에 넣으세요. 또한 내용을 부적절한 틀에 억지로 맞추지 마세요. 예를 들어 '방향별로 진행 중인 여러 작업'을 '상반기 진행 상황'이라는 시간적 틀에 억지로 넣지 마세요. 먼저 이 내용의 실제 구성 차원이 무엇인지 생각하세요(현재 상태는 방향별로, 흐름은 시간순으로). 자가 점검: 제목을 소리 내어 읽어보세요. 사람이 일반적으로 지을 법한 이름처럼 들리나요? '총: 올해의 목표'는 어색하고, '올해의 목표'가 자연스럽습니다.
표 작성법
열 이름은 쉬운 말로 쓰고, 가능하면 질문 형태로 작성합니다. 예를 들어 '사용자가 하는 일 / 시스템이 배후에서 하는 일 / 기다릴 필요가 있는지'처럼 쓰고, '동기화 진입점 / 비동기 링크 및 데이터 저장' 같은 내부 용어는 사용하지 않습니다.
셀은 완전한 짧은 문장으로, '누가 무엇을 했고, 결과가 무엇인지'를 한 문장으로 설명합니다.
기술적 세부 사항은 본문에 넣고, 표는 사람이 이해하기 쉽게 만드는 데에만 사용합니다. 전체 테이블 생성 문, 인터페이스 정의 등은 본문의 전용 섹션에 넣고, 표 안에 쌓지 않습니다.
그림: 언제 어떤 그림을 사용할까
그림으로 표현할 수 있는 프로세스는 텍스트로 쌓지 마세요. 표현하려는 것에 따라 그림을 선택합니다:
| 표현하려는 것 | 어떤 그림을 사용할까 |
|---|---|
| 로직 프로세스, 순서, 데이터가 단계별로 어떻게 흐르는지 | 시퀀스 다이어그램 (mermaid sequenceDiagram), 역할별로 수영(Swimlane) 사용 |
| 모듈 계층 구조, 의존 관계 | 아키텍처 다이어그램 (카드형 노드: 아이콘 + 제목 + 한 줄 설명, 계층별 색상 사용) |
| 상태 전이 (예: 초안 → 게시 → 내리기) | 플로우차트 또는 상태 다이어그램 (mermaid flowchart) |
이러한 그림을 실제로 Feishu에 넣는 방법(mermaid 보드, lark-whiteboard, lark-cli 사용법)은 references/feishu-tooling.md를 참조하세요.
제출 전 자가 점검
제출하기 전에 이 목록을 항목별로 검토하고, 하나라도 통과하지 못하면 돌아가서 수정합니다:
- 본문과 표에 화살표 체인(A → B)이 없나요? 화살표는 그림에만 있나요?
- 각 문단이 2-3줄을 넘지 않나요?
- 설명되지 않은 업계 용어(은어)가 없나요? 용어가 처음 등장할 때 쉬운 설명을 덧붙였나요?
- 프로세스 관련 내용은 그림으로 표현되었고, 텍스트로 쌓지 않았나요?
- 표 셀은 완전한 짧은 문장인가요? 열 이름은 쉬운 말인가요?
- '왜 이렇게 선택했는지'에 대한 긴 추론은 삭제하고 결론만 남겼나요?
- 장식용 이모지나 컬러 콜아웃 박스(callout)가 없나요? 강조는 굵은 소제목으로, 메모는 인용 블록을 사용했나요?
- 동그라미 숫자 ①②③, 상태 이모지 ✓ ◐ 등 키보드로 입력할 수 없는 문자가 없나요?
- 굵게 강조는 절제되었나요? 각 섹션에 최대 한두 개의 전반적인 결론만 있고, 명사 목록/방향어에 굵게 표시하지 않았나요?
- 제목과 표에 영어 단어가 주어로 사용되지 않았나요? 디자인 시안 영어 mock에는 한국어 주석을 달았나요?
- 제목은 내용을 직접 명명하고, '총:/분:/제1부:' 같은 구조적 접두사나 메타 설명이 없나요? 내용을 부적절한 시간적 틀에 억지로 넣지 않았나요?
관련 참조 자료
references/jargon.md: 업계 용어(은어) 대조표. 왼쪽 단어는 모두 오른쪽의 쉬운 말로 바꿉니다. 계속 업데이트됩니다.references/feishu-tooling.md: 그림을 Feishu에 넣는 방법에 대한 도구 참고 자료입니다 (mermaid 보드, lark-whiteboard, lark-cli).
이 스킬 자체도 이러한 규칙을 따릅니다
이 스킬의 SKILL.md, README, 참조 파일은 모두 위 규칙에 따라 작성되었습니다. 이 스킬을 수정할 때는 먼저 '제출 전 자가 점검'을 자신에 대한 점검으로 사용하세요: 장식용 이모지 없음, 화살표 체인 없음, 문단 짧음, 제목은 내용을 직접 명시. 규칙이 변경되면 SKILL.md와 README를 함께 업데이트하여 서로 일관성을 유지하세요.