openclaw-docs

OpenClaw Docs

개요

이 스킬은 OpenClaw 개발자 문서(API, SDK, CLI 도구, 통합, 퀵스타트, 플랫폼 가이드, 기술 제품 문서)를 작성, 편집 또는 리뷰할 때 사용합니다.

간결하고 도움이 되며 포괄적인 문서를 작성하세요: 첫 성공은 빠르게, 프로덕션에서는 정확하게, 디버깅 시에는 쉽게 훑어볼 수 있어야 합니다.

핵심 모델

Write the Docs 원칙으로 강화된 OpenClaw 문서 모델을 사용합니다:

• 개발자가 무엇을 하려는지로 시작합니다.
• 대안보다 권장 경로를 먼저 제시합니다.
• 예제를 실행 가능하고 현실적으로 만듭니다.
• 가이드는 작업 중심으로, 참조는 완전하게 유지합니다.
• 개발자가 실수할 수 있는 정확한 위치에 프로덕션 위험을 설명합니다.
• 개념, 가이드, API 참조, SDK, 테스트, 문제 해결을 연결하여 독자가 다시 읽지 않고도 이동할 수 있게 합니다.
• 문서를 제품 라이프사이클의 일부로 취급합니다: 구현 전이나 구현과 동시에 초안을 작성하고, 코드와 함께 리뷰하며, 최신 상태로 유지합니다.
• 각 페이지를 검색 가능하고, 주소를 지정할 수 있으며, 누적적이고, 명시된 범위 내에서 완전하며, 쉽게 훑어볼 수 있게 만듭니다.

구조

문서 유형을 작성 전에 선택하세요:

• 개요: 독자를 올바른 제품, 통합 경로 또는 가이드로 안내합니다.
• 퀵스타트: 최소한의 안전한 단계로 새 사용자를 작동 결과로 안내합니다.
• 주제 페이지: 주요 도메인 엔티티에 대한 종합적인 개요를 제공하며, 설정, 주요 하위 주제, 문제 해결, 심화 참조 링크를 포함합니다.
• 가이드: 사전 조건부터 프로덕션 준비까지 하나의 워크플로를 설명합니다.
• API 참조: 모든 객체, 엔드포인트, 파라미터, 열거형, 응답, 오류 및 버전 규칙을 정의합니다.
• SDK 또는 CLI 참조: 설치, 인증, 명령어 또는 메서드, 옵션, 예제 및 실패 모드를 문서화합니다.
• 테스트 가이드: 샌드박스 설정, 픽스처, 테스트 데이터, 시뮬레이션된 실패 및 라이브 모드 차이점을 보여줍니다.
• 문제 해결 가이드: 증상을 확인, 원인 및 해결 방법에 매핑합니다.

다음 기본 주제 페이지 구조를 사용하세요:

1. 제목: 주요 엔티티나 표면의 이름을 지정합니다.
2. 시작 개요: 제목이 없는 몇 문장으로 시작하여 그것이 무엇인지, 무엇을 담당하는지, 무엇을 담당하지 않는지 설명합니다. 페이지 자체가 개요 색인이 아닌 이상 ## 개요 제목을 추가하지 마십시오.
3. 요구 사항: 설정에 특정 계정, 버전, 권한, 플러그인, 운영 체제 또는 자격 증명이 필요한 경우에만 포함합니다.
4. 퀵스타트: 권장 설정 경로와 가장 작은 신뢰할 수 있는 검증을 보여줍니다.
5. 구성: 표면을 사용하는 데 필요한 최소 구성, 사용자가 선택해야 하는 일반적인 변형, 각 옵션이 설정되는 위치(CLI, 구성 파일, 환경 변수, 플러그인 매니페스트, 대시보드 또는 API)를 보여줍니다.
6. 주요 하위 주제: 독자의 의도에 따라 엔티티의 주요 개념, 워크플로 및 결정을 구성합니다. 각 주요 하위 주제를 자체 제목 아래에 배치하고, 일반적인 ## 하위 주제 섹션으로 묶지 마십시오.
7. 문제 해결: 명시적인 ## 문제 해결 제목 아래에서 일반적인 관찰 가능한 오류를 진단합니다.
8. 관련 항목: 가이드, 참조, 명령어, 개념 및 인접 주제에 대한 링크를 제공합니다.

주제 페이지는 퀵스타트보다 길 수 있지만, 완전한 참조가 되어서는 안 됩니다. 필드 테이블, API 계약, 좁은 내부 사항, 레거시 세부 정보 및 드문 디버깅 워크플로는 종합적인 개요를 방해할 때 링크된 참조 또는 문제 해결 페이지로 이동하십시오.

구성의 경우 작업에 중요한 옵션을 인라인으로 유지합니다. 전체 옵션 목록, 기본값, 열거형, 생성된 스키마 및 고급 설정은 참조 문서에 링크하십시오. 주제 페이지가 자체가 참조가 아닌 이상 주제 페이지에 완전한 구성 참조 테이블을 복제하지 마십시오.

다음 기본 가이드 구조를 사용하세요:

1. 제목: 구현 세부 사항이 아닌 결과의 이름을 지정합니다.
2. 시작: 독자가 한두 문장으로 무엇을 성취할 수 있는지 진술합니다.
3. 시작하기 전에: 계정, 키, 권한, 버전, 도구 및 가정을 나열합니다.
4. 경로 선택: 독자가 결정해야 하는 경우에만 옵션을 비교합니다.
5. 단계: 동사 중심의 제목을 사용하고 코드, 예상 출력 및 확인을 포함합니다.
6. 테스트: 통합이 작동한다는 가장 작은 신뢰할 수 있는 증거를 보여줍니다.
7. 프로덕션 준비: 보안, 멱등성, 재시도, 제한, 관찰 가능성, 마이그레이션 및 정리를 다룹니다.
8. 문제 해결: 워크플로를 유발하는 일반적인 오류를 가까이 포함합니다.
9. 참고 자료: 개념, API 참조, SDK 문서 및 인접 가이드에 대한 링크를 제공합니다.

탐색을 사용자 의도 기반으로 유지하십시오. 독자가 작업을 선택하기 전에 내부 제품 분류를 이해하도록 강요하지 마십시오.

문서 라이프사이클

코드와 동일한 규율로 문서를 작성하고 유지 관리하십시오:

• 명확하지 않은 제품, API, CLI 또는 구성 설계를 노출할 수 있을 만큼 일찍 문서 초안을 작성하십시오.
• 리포지토리 레이아웃이 허용하는 경우 문서 소스를 설명하는 코드, 구성, 명령어, 플러그인 또는 프로토콜 가까이에 두십시오.
• 중복된 진실을 피하십시오. 동일한 계약이 여러 곳에 나타나는 경우 표준 페이지를 선택하고 링크하십시오.
• 동작, 구성, API, CLI, 플러그인 또는 문제 해결 변경과 동일한 변경으로 문서를 업데이트하십시오.
• 오래된 문서를 제거하거나 리디렉션하거나 명확하게 표시하십시오. 부정확한 문서는 문서가 없는 것보다 더 나쁩니다.
• 적절한 검토자를 참여시키십시오: 동작에 대한 코드 소유자, 사용자 실패 모드에 대한 지원 또는 QA, 구조 및 스타일에 대한 문서 관리자.
• 이전 버전 지침은 사용자에게 필요한 경우에만 보존하고, 그렇지 않으면 현재 지원되는 동작을 문서화하십시오.

FAQ를 관련 없는 자료의 덤핑 그라운드로 사용하지 마십시오. 반복되는 질문을 작업, 개념, 문제 해결 또는 참조 페이지로 승격시키십시오.

작성 스타일

직접적이고 실용적인 어조로 작성하십시오:

• 현재 시제와 능동태를 사용하십시오.
• 지시할 때 독자를 "당신"으로 지정하십시오.
• 짧은 단락과 훑어보기 쉬운 목록을 선호하십시오.
• 구체적인 명사를 사용하십시오: "에이전트 프로필", "Gateway 웹훅", "플러그인 매니페스트", "세션 상태".
• 경고를 단계에 영향을 미치는 정확한 위치에 배치하십시오.
• 마케팅 언어, 과장, 일반적인 이점 및 모호한 주장을 피하십시오.
• 첫 번째 실행 가능한 단계 전에 긴 개념적 도입을 피하십시오.
• 제품에 비표준 계약이 없는 한 일반적인 개발자 개념을 과도하게 설명하지 마십시오.
• OpenClaw 제품 이름, 명령어 또는 식별자에 대문자가 필요한 경우를 제외하고 제목에는 문장 형식을 사용하십시오.
• 대상 또는 동작의 이름을 지정하는 설명적인 링크 텍스트를 사용하고, "이 페이지" 또는 "여기를 클릭"과 같은 모호한 링크를 피하십시오.
• 문화적으로 특정한 관용구, 폭력적인 관용구 및 문서를 번역하거나 훑어보기 어렵게 만드는 농담을 피하십시오.
• 접근 가능한 산문을 작성하십시오: 색상, 스크린샷 또는 시각적 위치에만 의존하여 지침을 이해하지 마십시오.

동작 또는 참조 표면을 설명하는 제목을 사용하십시오:

• 좋은 예: "에이전트 생성", "Slack 채널 구성", "플러그인 설치 복구"
• 피해야 할 예: "작동 방식", "내부 동작", "중요 참고 사항" (섹션이 실제로 그 형식을 필요로 하지 않는 한)

정확한 양태 언어를 사용하십시오:

• 필수 동작에는 "반드시"를 사용하십시오.
• 선택적 기능에는 "할 수 있습니다"를 사용하십시오.
• 기본 경로에는 "권장"을 사용하십시오.
• 알려진 함정에는 "피하십시오"를 사용하십시오.
• 개발자 결정을 변경할 때만 "이유"를 설명하십시오.

세부 수준

페이지 유형에 따라 세부 수준을 조정하십시오:

• 개요 페이지: 간결하게 작성하고, 독자가 선택할 수 있도록 도우십시오.
• 퀵스타트: 절차적으로 작성하고, 첫 번째 성공에 필요한 것만 포함하십시오.
• 가이드: 하나의 워크플로에 대해 완전하게 작성하고, 결정, 부작용 및 실패 처리를 포함하십시오.
• 참조: 완전하게 작성하고, 모든 필드, 기본값, 열거형, null 가능 값, 제약 조건, 응답 및 오류를 문서화하십시오.
• 문제 해결: 명시적으로 작성하고, 독자가 막혀서 관찰 가능한 확인이 필요하다고 가정하십시오.

실수가 비용이 많이 드는 곳에서는 세부적으로 들어가십시오:

• 인증 및 비밀 처리
• 금전 이동, 청구, 권한 및 취소 불가능한 작업
• 웹훅, 재시도, 중복 이벤트 및 순서
• 멱등성 및 동시성
• 샌드박스와 프로덕션의 차이점
• 버전 관리, 마이그레이션 및 이전 버전과의 호환성
• 제한, 속도 제한, 할당량 및 시간 초과
• 오류 코드 및 복구 경로
• 데이터 보존, 개인 정보 보호 및 규정 준수에 민감한 동작

개발자가 작업을 안전하게 완료하는 데 필요한 경우 이 세부 정보를 먼 참조에 묻지 마십시오.

예제

테스트 데이터를 사용하더라도 예제를 프로덕션 형태로 만드십시오:

• 완전히 복사하여 붙여넣을 수 있는 명령어나 스니펫을 선호하십시오.
• 현실적인 변수 이름과 값을 사용하십시오.
• <API_KEY> 또는 <CUSTOMER_ID>와 같은 꺾쇠 괄호 이름으로 자리 표시자를 명확하게 표시하십시오.
• 명령어 후 예상되는 성공 출력을 표시하십시오.
• 응답 형태가 중요한 경우 API 참조에 대한 전체 요청 및 응답 예제를 표시하십시오.
• 코드 블록당 하나의 개념 단위를 유지하십시오.
• 언어별 코드 펜스를 사용하십시오.
• 필요한 설정, 인증, 오류 처리 또는 정리를 숨기는 장난감 예제를 피하십시오.

여러 언어가 유용한 경우 독자가 동등한 것을 비교할 수 있도록 언어 간에 동일한 시나리오를 유지하십시오.

검색 가능성 및 탐색

모든 페이지를 독자가 찾고, 링크할 수 있고, 자신의 질문에 답변하는지 빠르게 결정할 수 있도록 설계하십시오:

• 목표 지향적인 제목과 헤딩을 사용하여 검색어와 일치할 가능성이 높도록 하십시오.
• 각 페이지를 "여기서 무엇을 할 수 있나요?"에 대한 간결한 답변으로 시작하십시오.
• OpenClaw 문서 색인에 필요한 메타데이터 또는 머리말을 포함하십시오.
• 문서 색인에 참여하는 OpenClaw 문서 페이지를 생성하거나 변경할 때 문서 목록 라우팅을 위한 "다음을 위해 읽기" 힌트를 추가하십시오.
• 이슈, PR, 지원 답변 및 채팅 응답의 링크에 대해 충분히 안정적인 섹션 제목을 유지하십시오.
• 자습서와 예제를 사전 조건에서 고급 작업으로 정렬하고, 참조 페이지는 조회에 도움이 될 때 알파벳 순서 또는 주제별로 정렬하십시오.
• 페이지가 의도적으로 부분적일 때 범위를 미리 명시하십시오.

API 참조 패턴

엔드포인트, 메서드, 객체 또는 명령어에 대해 다음을 포함하십시오:

1. 짧은 목적 설명.
2. 인증 또는 권한 요구 사항.
3. 경로, 쿼리, 헤더 및 본문 필드를 포함한 요청 형태.
4. 유형, 필수 여부, 기본값, 제약 조건, 열거형 값 및 부작용이 포함된 파라미터 테이블.
5. 객체 라이프사이클 상태가 포함된 반환 형태.
6. 코드, 원인 및 복구 지침이 포함된 오류 사례.
7. 실행 가능한 예제 요청.
8. 대표적인 성공 응답.
9. 관련 가이드 및 인접 참조 페이지.

중첩된 객체의 경우 자식 필드를 부모 근처에 문서화하십시오. 독자가 단일 요청의 형태를 이해하기 위해 페이지를 건너뛰게 하지 마십시오.

검증

제품 변경 사항과 마찬가지로 문서 변경 사항을 검증하십시오:

• 가능한 경우 관련 문서 빌드, 문서 색인, 포맷터, 링크 검사기 또는 생성된 문서 검사를 실행하십시오.
• 가능한 경우 페이지가 사용자에게 실행하라고 지시하는 명령어, 스니펫 및 예제를 실행하십시오.
• 스크린샷, UI 레이블, CLI 출력, 구성 키, 플래그, 기본값, 오류 및 파일 경로가 현재 동작과 일치하는지 확인하십시오.
• API, CLI, 구성, 생성된 참조 및 문제 해결 문서의 경우 산문 전용 리뷰보다 실행 가능한 검사를 선호하십시오.
• 검증 단계가 불가능한 경우 무엇이 검증되지 않았고 그 이유를 명시하십시오.

완전성 검사

페이지를 최종 확정하기 전에 다음을 확인하십시오:

• 첫 화면이 독자에게 그들이 성취할 수 있는 것을 알려줍니다.
• 권장 경로가 명확합니다.
• 사전 조건이 명시적이고 테스트 가능합니다.
• 예제가 문서화된 입력으로 실행될 수 있습니다.
• 페이지에 명확한 대상(사용자, 운영자, 플러그인 작성자, 기여자 또는 유지 관리자)이 있습니다.
• 테스트 모드와 프로덕션 모드 동작이 분리되어 있습니다.
• 보안에 민감한 값이 예제에 노출되지 않습니다.
• 모든 경고가 관련 단계에 연결됩니다.
• 엣지 케이스가 구현에 영향을 미치는 곳에 문서화됩니다.
• API 필드에 유형, 기본값, 제약 조건 및 오류가 포함됩니다.
• 문제 해결이 관찰 가능한 증상에서 시작됩니다.
• 관련 링크가 독자가 페이지를 복제하지 않고 계속할 수 있도록 도와줍니다.
• 페이지에서 지원을 받거나, 이슈를 제기하거나, 기여할 위치를 독자의 다음 단계와 관련된 경우 명시합니다.
• 페이지가 주장하는 범위에 대해 완전하거나, 제한 사항이 미리 명시됩니다.

리뷰 패스

다음 순서로 편집하십시오:

1. 반복과 일반적인 설명을 제거하십시오.
2. 올바르게 선택하는 데 필요하지 않은 한 개념적 배경을 첫 번째 유용한 작업 아래로 이동하십시오.
3. 수동적이거나 추상적인 표현을 구체적인 지침으로 대체하십시오.
4. 개요가 작업 맵처럼 읽힐 때까지 제목을 조정하십시오.
5. 프로덕션 안전을 위해 누락된 운영 세부 정보를 추가하십시오.
6. 예제의 복사-붙여넣기 정확성을 확인하십시오.
7. 가이드, 참조, SDK, 테스트 및 문제 해결 표면 간의 링크를 추가하십시오.
8. 검색 가능성, 주소 지정 가능성, 접근성 및 docs-as-code 검증을 확인하십시오.