Authoring

Start with the reader

문서가 답할 질문과 독자를 먼저 정합니다. 결론과 다음 판단을 앞에 두고 긴 근거·계약을 뒤에서 찾을 수 있게 합니다. 현재 동작·채택한 결정·제안·미확인 사항을 구분하며, 렌더링 성공을 실제 실행 결과로 소개하지 않습니다. 설계·메모·참조·조사는 같은 Markdown 렌더러를 사용합니다. 새로운 문서 종류를 지정할 필요가 없습니다.

Choose a representation

현재 본문 최대 폭은 900px이며 안쪽 읽는 폭은 약 834px입니다. 긴 설명을 표 셀에 압축하거나 열을 계속 늘리지 않습니다. 모바일에서는 표·코드 상자 내부의 가로 스크롤을 고려합니다. 그림만 보아야 알 수 있는 정보에는 본문 설명을 함께 씁니다.

Choose page boundaries

같은 화면이나 하나의 질문을 설명하는 내용은 한 문서의 ##·### 제목으로 묶습니다. 제목은 On this page에서 이동하므로 절마다 Markdown 파일을 만들 필요가 없습니다. 독립적으로 찾아보는 공통 API 참조, 별도 독자·작업을 가진 안내, 긴 부록만 하위 문서로 분리합니다. 본문 폭이 좁다는 이유만으로 파일을 나누지 않습니다. 긴 표를 설명으로 풀어 쓰는 것과 문서 경계를 정하는 것은 별개 판단입니다.

예를 들어 화면 설계 한 장은 범위 → 화면 구성 → 상태·질문 → API → 검증을 내부 제목으로 연결합니다. 여러 화면이 함께 쓰는 API 계약은 독립 참조 문서로 두고 각 화면에서 링크합니다. 페이지 수가 늘어 사이드바에서 현재 문서를 찾기 어려워지면 같은 읽기 흐름의 절을 먼저 합칠지 검토합니다.

Recipes

견본의 순서는 필요한 항목만 골라 사용합니다. 작은 메모에 모든 절을 채울 필요는 없습니다.

• 설계: 범위·핵심 결정 → 흐름·상태 → 미결 질문 → 계약·구현 참고 → 검증 조건
• 참조: 지원 범위·버전 → 값·입력·오류·예외 → 짧은 사용 예 → 출처
• 조사: 질문 → 관찰·근거 → 결론과 한계 → 남은 확인
• 변경·이전: 바뀌는 행동·영향 대상 → 이전/이후 → 적용 순서 → 검증·복구
• 검증: 확인 범위 → 환경·명령·관찰 → 확인하지 않은 것

설계의 가상 견본은 Design example, 조사·검증의 가상 견본은 Research example. 예시 앱의 API·업무 규칙은 라이브러리 기능이 아닙니다.

AI writing checklist

1. 현재 코드·제공 자료·실제 실행·외부 출처를 읽고 각각 무엇의 근거인지 기록합니다.
2. 원문의 숫자·조건·예외·ID·출처와 미확인 상태를 보존합니다. 답이 없는 질문을 채택 상태로 바꾸지 않습니다.
3. 같은 사실의 정본을 한 곳에 두고 다른 설명에서는 링크합니다.
4. 질문에 이유·선택지·추천 근거·미답변 시 영향을 남깁니다. 절차에 입력·예상 결과·완료 기준을 씁니다.
5. 일반 Markdown으로 충분한 내용은 새 문법이나 HTML 목업으로 복잡하게 만들지 않습니다.
6. 링크·이미지·목차·코드·반응형을 확인하고 사실·동작 검증과 별도로 보고합니다.
7. 바뀐 판단과 남은 검증을 관련 요약·참조에 함께 반영합니다.

에이전트 지침에서 이 문서를 참조할 수 있습니다. 사용자 저장소의 AGENTS.md를 덮어쓰지 않습니다. 언어·담당 체계·출처 우선순위와 문서 이름은 각 프로젝트가 정합니다.

Migrate existing documents

원본 목록·앵커·이미지·코드를 먼저 수집하고 원본을 보존합니다. 정보를 유지한 첫 변환 후 비교표와 항목별 설명을 구분하고, 같은 읽기 흐름은 내부 제목으로 묶습니다. 별도 독자·목적을 가진 상세만 하위 문서로 나눕니다. 원본의 모든 절을 독립 페이지로 만들지 않습니다. 병합 셀과 질문 참조는 관계를 읽어 옮기며, 없는 대상을 추측하지 않습니다.

구현할 예정인 시각화·테마 모듈은 Roadmap. 원시 HTML은 사용할 수 있지만 다른 사이트의 CSS·JS가 자동 이식되거나 JSX가 실행되지는 않습니다.