사용 시기
Word/.docx 대신 Typst를 사용하여 상세한 기술 문서(조사 보고서, 아키텍처 요약, 근본 원인 분석 문서, 마이그레이션 설명)를 작성하세요. 대상 문서:
- 실제 기술 보고서처럼 읽혀야 함: 제목 페이지, 요약, 번호가 매겨진 섹션
- 인쇄물에서 보기 좋게 보여야 함(LaTeX 스타일 조판:
#set page,#set heading(numbering: "1.1"), 양쪽 정렬 본문) - 다이어그램 포함(아키텍처/흐름 다이어그램, 단순한 산문이 아님)
- 표 포함(비교 표, 증거 표, 상태 표)
- 출처에 대한 클릭 가능한 링크 포함(채팅 스레드, GitHub PR, 위키 페이지)
- 이름/날짜가 포함된 직접 인용(메시지, PR 본문)을 통해 주요 출처 인용
트리거 구문: "이거 정리해 줘", "문서 만들어 줘", "typst로 해 줘", "이거 보고서로 만들어 줘" — 특히 여러 소스(채팅 검색, GitHub PR 검토, 라이브 시스템 증거)를 종합하여 공유 가능한 결과물을 만들어야 하는 조사 후에 사용합니다.
컴파일하기 전에 개인 Typst 주의사항 파일(예: ~/notes/typst.md)을 보관하고 참조하세요. 알려진 구문 트랩(각주 배치, #N 충돌, fletcher 가져오기, 표 열 크기 조정 등)을 기록하고, 새로운 컴파일 오류 클래스가 발견될 때마다 추가하세요.
중요 구문 규칙(typst compile 전 점검 목록):
- 굵게 표시는 단일
*word*이며, 절대**word**가 아님: Markdown 이중 별표는 수십 개의 컴파일러 경고를 발생시킵니다(warning: no text within stars; using multiple consecutive stars has no additional effect). - 수학 모드 문자열은 따옴표 필요:
$ ... $안에서$Count=65$또는$RTO$와 같은 여러 문자 식별자는 컴파일 실패(unknown variable).$"Count"=65$로 쓰거나 코드를 백틱(`Count=65`) 안에 넣으세요. - 수학에서 LaTeX 백슬래시 연산자 사용 금지:
$\approx$는 실패(unknown variable: pprox). Typst는 백슬래시 없이 기호를 직접 사용:$approx$.
콘텐츠는 깊이 있게, 프레젠테이션은 리소스를 의식하며
모든 보고서를 구성하는 두 가지 지침:
- 진정한 기술 콘텐츠를 깊이 있게 다루세요. 얕은 요약이 아니라 극도로 깊은 기술적 깊이를 목표로 하세요. 더 많은 원시 콘솔 출력, 더 많은 아키텍처/상태 머신 다이어그램, 하드웨어 관련 주제의 경우 레지스터/비트 필드 또는 디지털 회로 수준의 세부 정보, 소프트웨어 실행 관련 주제의 경우 CPU 명령어/어셈블리 수준의 세부 정보를 포함하세요. 초안이 5-6페이지에서 "완료"되었다고 느껴지면, 한 단계 더 깊이 파고들 신호입니다(추가
redis-cli/systemctl/레지스터 덤프, 추가 아키텍처 다이어그램, 추가 업계 비교 관점). 멈추지 마세요. 아래 "깊이 기대치"에서 구체적인 섹션별 분석을 참조하세요. - 하지만 프레젠테이션은 리소스를 의식하고 콘텐츠는 그렇지 않게 하세요. 콘텐츠의 깊이와 스타일링의 리소스 의식은 별개의 축입니다. 사실/증거/다이어그램은 깊이 있게 가져가되, 시각적 프레젠테이션 자체는 잉크를 절약하게 유지하세요: 밝은 색조 배경 + 색상 테두리/텍스트를 단색 채우기 대신 사용하고, 색상은 의미가 있는 곳에만 사용하세요(아래 색 구성표 참조). 잉크 절약은 페이지 본문 잉크에 적용되며, 제목 블록에는 적용되지 않습니다. 제목은 상자로 처리됩니다(아래 색 구성표 항목 1 참조). 진정한 기술적 내용이 더 많은 페이지를 만드는 것이 목표이며, 페이지당 더 많은 단색 잉크를 사용하는 것은 아닙니다.
워크플로
- 먼저 모든 증거를 수집하세요(채팅 검색, GitHub PR 읽기, 라이브 명령 출력, 이슈 트래커/채팅 사전 조사) — 작성 중간에
.typ파일을 시작하지 말고, 모든 것을 종합한 후에 작성하세요. - 위의 구조 템플릿(단일 악센트 상자 제목, 가는 선이 있는 악센트 제목, 밝은 색조 표 헤더, 의미에 따라 선택된 2-4개의 주요 순간에 의미론적 콜아웃, 밝은 콘솔 블록, 노드 그래프를 위한
#figure로 감싼 fletcher 다이어그램, 기본적으로 목차 없음)을 사용하여 하나 또는 두 개의write/eval호출로 전체.typ소스를 작성하세요. fletcher를 사용하는 경우, 항상 파일 시작 부분에#import "@preview/fletcher:0.5.7": diagram, node, edge를 포함하세요. 이 가져오기를 생략하는 것은 가장 흔한 첫 번째 컴파일 오류입니다. - 컴파일:
typst compile file.typ(파일이 있는 작업 디렉토리에서 실행 — 세션당 한 번typst --version으로 바이너리 사용 가능 여부 확인, fletcher를 사용하는 경우 임시/tmp테스트 컴파일로 네트워크/패키지 해결을 실제 문서에 연결하기 전에 확인). 컴파일 오류 발생 시, 처음부터 디버깅하기 전에 주의사항 노트 파일을 확인하세요. - 완료를 선언하기 전에 항상 시각적으로 확인 — 모든 페이지를 PNG로 렌더링(
typst compile --format png --ppi 100 file.typ "page-{p}.png"— 출력 패턴을 따옴표로 묶음)하고 각 PNG를read하여 레이아웃/간격/렌더링을 검사하세요. 특히 다이어그램, 표 또는 콜아웃이 있는 페이지를 주의 깊게 검사하세요. 3개 이상의 가장자리 또는 양방향 가장자리 쌍이 있는 다이어그램은 레이블 충돌에 특히 주의해야 합니다. - 그런 다음 별도의 콘텐츠 읽기 패스를 수행하세요 — 레이아웃 확인은 콘텐츠 확인이 아닙니다. 4단계는 아무것도 잘못 렌더링되지 않았음을 증명할 뿐입니다. 아무것도 사실임을 증명하지 않습니다. 렌더링된 모든 페이지를 다시
read하고, 이번에는 출처 자료에 대해 산문을 읽고, 특히 다음을 찾으세요: (a) 챕터가 삽입될 때 구식이 된 수동으로 입력된 섹션 상호 참조("§9.1.3 참조"); (b) 출처에 비해 주장이 반전되거나 전치된 표 셀; (c) 주요 아티팩트가 아닌 다른 곳에서 전사된 숫자 —[INFERENCE]로 표시하거나 확인하세요. 실제로 필요함이 확인됨: 전체 레이아웃 패스를 통과한 문서에도 여전히 매달린§참조와 사실상 반전된 표 셀이 포함되어 있었으며, 둘 다 읽기를 통해서만 발견되었습니다. 한 번에 작성된 40KB 문서는 컴파일되었다고 해서 교정된 것이 아닙니다. - 최종
.typ+.pdf를 프로젝트의 문서 위치(예:docs/generated/)로 이동하고 둘 다 커밋한 다음, 중간 PNG 확인 파일을 삭제하세요 — 소스를 컴파일된 출력과 함께 보관하여 나중에 다시 편집할 수 있도록 하세요.
의미론적 마크업 사용
Typst의 자체 접근성 가이드에 따라: 일반 텍스트/산문을 해당 요소처럼 보이게 수동 스타일링(예: #text(size: 16pt, weight: "bold")[Heading])하는 대신 항상 실제 의미론적 요소(= Heading, #quote(...), #table(...))를 사용하세요. "제목처럼 보이는" 병렬 규칙을 절대 발명하지 말고, 항상 실제 마크업 요소에서 모양을 파생시키세요.
색 구성표
- 본문 글꼴:
New Computer Modern. 기준은 "LaTeX처럼"입니다 — NCM은 LaTeX 모양이며 Typst에 포함되어 있으므로 항상 해결됩니다. 시스템에 설치되지 않은 글꼴은 절대 선택하지 마세요(typst fonts로 확인). Typst는 누락된 패밀리에 대해 경고만 하고 자동으로 대체되므로, 문서는 깨끗하게 컴파일되지만 잘못 보입니다.unknown font family경고가 나타나면, 참을 수 있는 경고가 아니라 수정해야 할 결함입니다. - 의미론적 콜아웃 팔레트. 녹색
#1a7f37, 노란색#9a6700, 빨간색#cf222e, 파란색#0969da, 보라색#6639ba, 주황색#bc4c00; 콘솔/표 색조#f2f6fb/#eaf1fb테두리#9fb8d6/#c8d6e8. 인라인 및 블록raw는 시스템에 있는 고정폭 글꼴(예:Consolas,JetBrains Mono,Menlo)을 사용해야 합니다.
크롬에만 사용되는 하나의 구조적 악센트 색상과 의미 전달을 위한 의미론적 콜아웃 블록. 이것은 정착된 패턴입니다. 처음부터 다시 유도하지 말고 기본적으로 적용하세요:
- 제목 블록: 가운데 정렬된 색상 텍스트 + 테두리 상자. 제목 주위에
#box(fill: white, stroke: 1.5pt + accent, ...)를 사용하세요. - 표 헤더: 밝은 색조 채우기 + 악센트 색상 텍스트, 절대 단색 채우기를 사용하지 마세요.
- 의미 있는 결과에 대한 의미론적 콜아웃 블록 — 여기서 추가 색상이 사용되는 이유는 기능적이기 때문이지 장식적이지 않기 때문입니다. 콘텐츠에 맞는 것을 사용하세요. 모든 것을 모든 문서에 강제로 넣지 마세요. 보고서당 총 2-4개의 콜아웃이 적절한 밀도이며, 문단당 하나가 아닙니다.
- 확인됨 (녹색 체크 표시) — 확인된 양호한 결과, 한 줄.
- 이상 징후 (노란색 느낌표) — 예상치 못했지만 아직 결함으로 확인되지 않음.
- 확인된 결함 (빨간색 X) — 확인된 잘못된 결과, 한 줄.
- 참고 (파란색 정보) — 강조할 가치가 있는 중요하지 않은 관찰.
- 팁 (보라색 전구) — 도움이 되는 제안 또는 모범 사례.
- 열린 질문 (주황색 물음표) — 진정으로 해결되지 않은 불일치 또는 질문.
- 인쇄 가독성에 도움이 되는 경우 문서/섹션별로 색조를 변경하세요.
- 다이어그램 상자 색상은 역할 기반/의미론적으로 유지됩니다.
- 어디에도 큰 단색 어두운 색상 채우기를 사용하지 마세요 (예: 흰색 텍스트가 있는 전체 진한 파란색 배너). 섹션 제목: 색상 텍스트 + 아래에 가는 색상 선, 채워진 색상 밴드나 상자가 아닙니다.
- 콘솔/코드 출력 블록: 밝은 색조 배경, 회색이 아님. 평평한
#f4f4f4회색은 단조롭고/복사기처럼 읽힙니다. 미묘한 일치하는 테두리가 있는 밝은 색조를 사용하세요. - 챕터 사이에
#pagebreak()를 절대 사용하지 마세요. 모든=제목 앞에 페이지 나누기를 삽입하면 챕터당 반 페이지의 빈 종이가 남고 인쇄 시 실제 용지를 낭비합니다. 섹션이 흐르도록 두세요. 중간 페이지에서 새 챕터가 시작되는 것이 올바릅니다. 허용되는 유일한#pagebreak()는 제목 페이지와 본문을 구분하는 하나뿐입니다.
두 가지 기본 섹션 — 요청 없이 포함하세요
- 경쟁사/업계 맥락. 대안은 이 문제를 어떻게 해결하며, 이 아키텍처 위치는 구조적으로 무엇을 얻고 잃는가? 각 장점을 해당하는 테스트 가능한 위험으로 구성하세요. 실제 경쟁사 문서에서 나온 것이 아니라면 섹션을 일반 업계 지식으로
[INFERENCE]로 표시하세요. - 자동화/테스트 하니스, 구체적으로. 정확한 호출, 러너 호스트, venv 및 고정된 종속성, 마커 선택, 수집된 vs 선택 해제된 vs 실행된 카운트를 읽는 방법. "스위트가 있다"는 것은 적용 범위가 아닙니다.
그림 배치: 다이어그램/표를 #figure(...)로 감싸고, Typst가 배치하도록 두세요
Typst의 자체 레이아웃 지침에 따라 그림은 기본적으로 콘텐츠 흐름에 인라인으로 배치되지만, 다이어그램이나 표를 #figure(..., caption: [...])로 감싸면 placement: top/placement: bottom을 잠금 해제하여 Typst가 문단 중간에서 어색하게 콘텐츠를 분할하는 대신 페이지 상단/하단으로 띄울 수 있습니다. 항상 실제 캡션이 있는 #figure(...) 래퍼로 다이어그램을 제공하세요(산문에서 떠다니는 베어 #diagram(...) 호출을 절대 사용하지 마세요) — 이것은 또한 @sec-label을 통해 다이어그램을 상호 참조 가능하게 하고 스크린 리더/재사용 도구에 적절한 의미론적 그림+캡션 쌍을 제공합니다(단순히 레이블이 없는 이미지가 아님).
노드/가장자리 다이어그램을 위한 Fletcher
작동 패턴, 컴파일 및 렌더링 확인됨(위의 배치 지침에 따라 #figure로 감싸기). 가져오기를 기억하세요(워크플로 2단계 참조) — 이 스니펫은 파일 상단에 이미 있다고 가정합니다:
#figure(
diagram(
node-stroke: 0.6pt,
spacing: (3em, 2em),
node((0,0), [Step 1], fill: rgb("#dbe9ff"), corner-radius: 4pt),
node((0,1), [Step 2], fill: rgb("#dbe9ff"), corner-radius: 4pt),
edge((0,0), (0,1), "-|>", bend: 10deg),
edge((0,1), (0,0), "-|>", bend: 10deg),
),
caption: [인라인 레이블이 여기서 생략되었으므로 두 방향/가장자리를 모두 설명하는 한 줄 캡션.],
)
좌표는 (열, 행) 튜플입니다. node-stroke/fill/corner-radius는 개별 노드 스타일을 지정합니다. edge(from, to, "-|>")는 화살표를 그립니다(마크 문자열, 키워드 인자가 아님, 화살촉을 선택합니다 — "-|>" 및 "->" 모두 작동함; 점선 화살표의 경우 "..|>"). 여러 개의 독립적인 체인은 체인당 다른 열 인덱스와 체인당 stroke: none이 있는 헤더 행 노드를 사용하여 하나의 diagram(...) 호출을 공유할 수 있습니다. 가장자리 레이블은 하나의 짧은 단어/구로 유지하고 전체 설명을 그림의 caption으로 옮기세요. 단어보다 긴 인라인 가장자리 레이블은 전형적인 레이블 충돌 실패입니다.
깊이 기대치: 기본값은 긴 형식, 너드 수준의 깊이, 요약이 아님
특별히 짧은 것을 요청하지 않는 한, 전체 조사 보고서는 10-12페이지 렌더링을 목표로 하세요. 짧고 정확하지만 얇은 보고서는 효율적인 결과가 아니라 실패 모드입니다. 구체적으로 "깊이 들어간다"는 것은 주제가 지원하는 곳마다 다음을 포함함을 의미합니다:
- 전체 원시 콘솔/로그 출력, 잘린 스니펫이 아님 — 라이브 시스템 증거에서 나온 모든 주장에 대해 실제 명령 + 실제 출력을 그대로 포함.
- 최소 하나의 아키텍처 또는 상태 머신 다이어그램(위의 fletcher 사용)으로 실제 부품이 어떻게 연결되는지 보여주며, 단순히 산문으로 설명하는 것이 아님.
- 레지스터/비트 필드 또는 디지털 회로 수준의 세부 정보(주제가 하드웨어와 관련된 경우, 예: 특정 구성 레지스터의 비트 레이아웃, 신호 타이밍 다이어그램, ASIC 블록의 포트 매핑 테이블, 실제 드라이버 소스에서 가져온 실제 구조체/opcode 정의) — "하드웨어가 X를 한다"에서 멈추지 말고 실제 메커니즘을 보여주세요.
- CPU 명령어/어셈블리 또는 시스템 호출 수준의 세부 정보(주제가 소프트웨어 실행과 관련된 경우, 예: 드라이버가 실제로 발행하는 시스템 호출, 핫 경로의 디스어셈블리 모습) — "드라이버가 X를 한다"에서 멈추지 말고 실제 코드 경로를 보여주세요.
- 전용 업계/외부 맥락 섹션(아래 참조) — 내부 메커니즘을 고립되어 제시하지 마세요.
- 진정한 사전 기술/이력 검색 — 이슈 트래커, 채팅 기록, git 기록을 확인하여 이 정확한 질문이 이전에(심지어 몇 년 전에) 질문되었는지 확인하세요. 몇 년 묶은 열린 질문을 닫는 보고서는 결과를 완전히 새로운 것으로 취급하는 보고서보다 더 강력한 증거입니다.
구조: (1) 제목 + 요약, (2) 배경, (3) 증거 타임라인/방법론 — 각각의 고유한 결과에 대한 하위 섹션과 자체 인용 증거 블록, 일반적으로 가장 긴 섹션, (4) 주제의 이름이 다른 것과 겹치는 경우 명확화 섹션, (5) 비교 표, (6) 업계/외부 맥락, (7) 다이어그램과 쌍을 이루는 번호가 매겨진 종단 간 목록으로서의 아키텍처/종합, (8) 구체적인 후속 조치가 있는 열린 질문, (9) 원래 조사로의 연결, (10) 본문에서 정리된 전체 원시 증거가 포함된 부록. 초안이 완료되었지만 짧다고 느껴질 때는 기존 산문을 늘리는 대신 실제 조사를 한 번 더 수행하세요(또 다른 라이브 확인, 또 다른 레지스터 덤프, 또 다른 웹 검색, 또 다른 다이어그램, 사전 기술에 대한 또 다른 기록 검색) — 깊이는 실제 콘텐츠에서 나와야 하며, 결코 재구성/확장에서 나와서는 안 됩니다.
[참고: 원본 SKILL.md가 잘렸으므로 나머지 내용은 번역할 수 없습니다.]