문서 표준
모든 페이지를 검색 가능하고, 초보자가 읽을 수 있으며, 에이전트와 유지보수자에게 정확하게 만드세요. 계층, 작성 규칙, 예산 및 슬롭 체크리스트는 docs/AGENTS.md에 있습니다. 이 스킬은 이를 적용하기 위한 워크플로우를 담당합니다. 사실 당 하나의 소유자를 유지하세요. 소스, 테스트, 생성된 카탈로그, README, 가이드 및 에이전트 노트 각각은 고유한 사실을 유지합니다. 이는 지침이며 체크리스트가 아닙니다.
워크플로우
요청된 각 범위에 대해 다음 순서를 따르세요. 일반적인 독자 경로를 간결하게 유지하되, 실패, 소유권, 제한 사항 또는 기타 필수 계약을 단어 수를 줄이기 위해 삭제하지 마세요.
- 루트 및 하위 트리
AGENTS.md파일,docs/AGENTS.md, 대상 페이지, 해당 소스 및 테스트, 그리고 탐색 소유자를 읽으세요. - 페이지를 하나의 주요 작업과 독자(빠른 시작, 사용자 작업 가이드, 기여자 튜토리얼, 아키텍처 개요, 모듈 참조, 생성된 참조, 에이전트 지침, 결정 기록 또는 스크래치)로 분류하세요.
- 페이지를 가장 가까운 소유자에게 배치하세요. 모듈 계약은 모듈 코드 옆에 두고,
docs/는 모듈 간 학습, 사용자, 개발자 및 아키텍처 자료에 사용하세요. - 세부 사항을 작성하기 전에 독자의 시작 상태, 관찰 가능한 결과, 가능한 실패, 복구 경로 및 다음 유용한 깊이를 정의하세요.
- 페이지 구조에 제공된 순서대로 작성하세요: 제목, 요약, 목차, 사용자 대면 콘텐츠, 개발자 대면 콘텐츠, 선택적 심화 탐구.
- 프로필이
surfaces.bilingual-docs를 활성화하면 동일한 패스에서 대응 버전을 업데이트하고 제목, 목록, 표, 코드 및 링크를 줄 단위로 정렬하세요. - 모든 주장을 코드, 테스트, 생성기, 패키지 메타데이터 또는 현재 결정 소유자에 대해 검증하고, 페이지가 지시하는 작업을 실행하세요(아래 사실 확인 절차 참조). 파생 아티팩트보다 먼저 소유자를 업데이트하세요.
- 프로필의
commands.docs-check및git diff --check를 실행한 다음, 전체 diff를 한 번은 정확성을 위해, 한 번은 간결성과 적합성을 위해 다시 읽으세요.
사실 확인 절차: 테스트하고, 가정하지 마세요
문서는 오늘날 제품이 어떻게 작동하는지를 설명하며, 작업 주장에 대한 허용 가능한 증거는 이를 실행한 것뿐입니다. 이는 명령, 기본값, 오류, 출력 또는 플랫폼 차이를 주장하는 모든 새 페이지와 모든 새 단락에 적용됩니다.
- 설치 또는 사용법 지침을 작성하기 전에 주제를 분류하세요. 폴더 이름이 아닌 사실(매니페스트, 진입점, 내보내기)을 읽으세요. 라이브러리, 플러그인, CLI 및 서비스는 각각 다른 사용법 경로를 가집니다. 다른 종류를 위해 작성된 지침을 복사하지 마세요.
- 현재 체크아웃에 대해 주장된 모든 작업을 실행하세요. 페이지에 표시될 그대로 각 명령, 구성 스니펫 및 예제를 실행하고, 경고 및 실패 모드를 포함하여 관찰한 내용만 기록하세요. 주장이 자격 증명이나 접근할 수 없는 네트워크에 의존하는 경우, 그렇게 명시하고 동작을 단언하는 대신 확인 소유자를 지정하세요.
- 재현할 수 없는 것은 삭제하세요. 명령, 필드, 기본값 또는 동작을 메모리, 유추 또는 이웃 README에서 가져오지 마세요. 주장을 재현할 수 없는 경우, 테스트가 아닌 주장을 수정하세요.
- 이전 문서를 최신 기본 브랜치와 비교하세요. 기존 페이지를 수정하기 전에 기본 브랜치를 가져와서 비교하고, 이전 산문이 아닌 코드에 대해 오래된 진술을 수정하세요.
어조 규칙
- 요약은 주제가 하는 일을 설명합니다. 요약 및 사용자 대면 섹션은 독자가 주제로 할 수 있는 일(결과, 선택 시기, 주요 비용)을 설명하며, 내부 정체성이나 등록은 절대 설명하지 않습니다. 소스 식별자는 독자가 구성, 명령 또는 공개 API에서 직접 사용하는 경우에만 생략하세요.
- 개발자 섹션은 설명하고, 나열하지 않습니다. 개발자 세부 사항은 디자인 개념, 아키텍처 및 대략적인 데이터 흐름을 포함하여 작동 방식을 이해하기에 충분하고, 정확한 세부 사항을 위해 코드에 링크합니다. 전체 API 카탈로그, 열 목록 또는 API 문서 재진술은 없습니다.
- 현재 상태만. 일반 문서는 현재 코드베이스를 설명합니다. 기록은 에이전트 노트, 사후 분석, 릴리스 노트 및 업그레이드 가이드에 속합니다.
- 통제된 기술 영어. 모호성이 동작을 변경할 수 있는 경우 각 문장에 명시적 행위자와 하나의 주요 동작을 제공하고, 개념당 하나의 용어를 재사용하고, 중첩된 지침을 분할하고, 양상 및 예외를 보존하세요. 페이지 구조를 참조하세요.
품질 기준
- 간결함: 일반 경로에는 결과에 필요한 사실만 포함됩니다. 완전한 진실은 한 링크 또는 세부 사항 계층 떨어져 있습니다.
- 직관적: 전제 조건은 종속 개념보다 먼저 오고, 하나의 다음 작업이 명확하며, 제목은 독자가 검색하는 용어를 사용합니다.
- 친근함: 독자는 성공을 인식하고, 행동하기 전에 위험을 이해하고, 가능한 실패에서 복구하며, 더 깊이 들어갈지 선택할 수 있습니다.
- 정확함: 각 내구성 있는 주장은 하나의 소유자와 위험에 비례하는 확인 경로를 가집니다.
- 에이전트가 읽을 수 있음: 안정적인 제목, 앵커, 용어 및 소유권은 전체 코퍼스를 로드하지 않고 대상 검색을 지원합니다.
- 초보자에게 완전함: 저장소 컨텍스트가 없는 엔지니어는 3~5개의 링크된 페이지를 통해 관련 아키텍처 또는 기능을 재구성할 수 있습니다.
포괄적인 참조에 보편적인 단어 제한을 적용하지 마세요. 항목 경로 길이, 조회당 스캔된 관련 없는 자료 및 가장 큰 섹션을 측정하고, 검색 비용이 높은 경우 기존 도메인 소유자로 분할하세요.
코퍼스 감사
docs/AGENTS.md의 작성 순서를 범위 내의 모든 사람 대상 문서(에이전트 노트 제외)에 적용하세요. 문서를 찾고 주제를 명시하고, 허용된 세부 사항을 설정하고 더 깊은 설명을 소유하는 하위 항목으로 이동하고, 경로가 아닌 의도된 사용에서 튜토리얼 또는 참조를 분류하고, 실질적인 혼합 형식을 분할하세요. 이동은 동일한 변경에서 수정된 모든 인바운드 링크와 함께 원자적입니다. 생성된 카탈로그는 수동으로 편집되지 않습니다.
그런 다음 docs/AGENTS.md에서 슬롭 체크리스트를 찾으세요. 가장 저렴한 프로브부터: 추론 기록 누출에 대해 trim-cot-leakage를 사용하고, 중복 규칙에 대해 독특한 구문을 검색하고, 수동으로 작성된 카탈로그를 권위 있는 소유자로 대체하고, 구현된 에이전트 노트에서 사양 언어를 제거하세요. 산문을 제거하면 동작 설명보다는 약속된 동작이 변경되는 경우, 먼저 동작 변경을 제안하세요(find-simplifications 참조). 모든 하중 지지 규칙을 유지하되, 가급적 1~3줄과 그 근거에 대한 링크로 유지하세요.
상세 참조
- 페이지 구조 및 스타일: 페이지 순서, 섹션 진행, 접기, 통제된 기술 영어 및 강조.
- 검토 기준: 초보자 테스트, 증거 검토 및 README 검토.
문장 수준 계약 범위 및 편집 판단에 대해 prose-standard를 사용하세요.