openclaw-refactor-docs

OpenClaw 문서 리팩터링

개요

사용자가 대상 OpenClaw 문서 페이지를 제공하고 다시 작성, 리팩터링, 재구성, 분할, 축약 또는 개선을 요청할 때 이 스킬을 사용하세요.

이 스킬은 technical-documentation을 기반으로 합니다. 스타일, 페이지 유형, 구조, 예제, 검색 가능성 및 검증을 위해 해당 스킬을 사용하세요. 이 스킬은 주요 문서 리팩터링 중에 정확한 동작 정보가 손실되는 것을 방지하는 데 필요한 재작성 워크플로를 추가합니다.

입력

필수:

• docs/plugins/codex-harness.md와 같은 대상 문서 페이지 경로.

선택 사항:

• 원하는 페이지 유형(예: 주제 페이지, 가이드, 참조, 문제 해결).
• 구체적인 목표(예: 기본 페이지 축약, 세부 정보를 참조 페이지로 이동, 현재 CLI 동작과 일치).
• 관련 소스 파일, 스키마, 명령, 테스트, 스펙 또는 PR.

대상 페이지가 없거나 모호한 경우, 편집 전에 한 가지 간결한 질문을 하세요. 그렇지 않으면 진행합니다.

작업 계약

명시된 범위 내에서 대상 페이지를 더 유용하고 간결하며 포괄적으로 리팩터링합니다.

재작성을 행동 사실을 버릴 수 있는 권한으로 취급하지 마십시오. 기존 자료를 보존, 확인, 이동 또는 명시적으로 폐기하세요. 부정확한 문서는 장황한 문서보다 나쁩니다.

다음 분할을 선호합니다:

• 주제 또는 가이드 페이지는 80/20 경로, 독자가 내려야 할 결정, 안전한 설정, 가장 작은 신뢰할 수 있는 검증, 일반적인 오류 및 이후 링크를 다룹니다.
• 참조 페이지는 전체 필드, 기본값, 열거형, 제한, 우선 순위 규칙, API 계약, 세부 내부 사항 및 드문 디버깅 세부 정보를 다룹니다.
• 문제 해결 페이지는 관찰 가능한 증상에서 시작하여 확인, 원인 및 수정 사항에 매핑됩니다.

워크플로

1. 문서 표준 로드

먼저 ../technical-documentation/SKILL.md를 읽으십시오. 리팩터링 전반에 걸쳐 페이지 유형, 스타일, 예제, 탐색 및 검증 지침을 적용합니다.

가능하면 pnpm docs:list를 실행한 다음 대상 페이지와 리팩터링에 필요한 진입점, 참조 또는 관련 페이지만 읽습니다.

2. 페이지 분류

편집 전에 technical-documentation에서 의도된 페이지 유형을 결정합니다.

현재 페이지가 페이지 유형을 혼합하는 경우, 기본 페이지 유형을 선택하고 다른 자료가 속한 위치를 계획합니다:

• 전체 계약을 기존 또는 새 참조 페이지로 이동합니다.
• 증상 기반 자료를 기존 또는 새 문제 해결 페이지로 이동합니다.
• 좁은 설정 워크플로를 기본 경로를 방해할 때 가이드로 이동합니다.
• 독자가 워크플로를 완료하는 데 필요한 간결한 라우팅, 결정 및 안전 세부 정보를 기본 페이지에 유지합니다.

3. 기존 사실 보존 및 감사

다시 작성하기 전에 이전 페이지에서 작업 목록을 만듭니다. 다음을 포함합니다:

• 구성 필드, 플래그, 명령, 슬래시 명령, 환경 변수, 기본값, 열거형, nullable 값 및 제약 조건.
• 우선 순위 규칙, 폴백 동작, 상한, 제한, 속도 제한, 시간 초과, 라이프사이클 상태, 대기열 동작 및 호환성 규칙.
• 인증, 권한, 승인, 샌드박스, 안전, 개인정보 보호 및 파괴적 작업 동작.
• 설정 요구 사항, 지원되는 버전, 종속성, 운영 체제, 자격 증명 및 계정 요구 사항.
• 오류 메시지, 문제 해결 증상, 진단 및 복구 단계.
• 예제, 예상 출력, 명령 라우팅 테이블 및 상호 링크.

각 사실에 대해 하나의 결과를 선택합니다:

• 리팩터링된 대상 페이지에 유지합니다.
• 특정 기존 페이지로 이동합니다.
• 특정 새 페이지로 이동합니다.
• 현재 소스가 더 이상 사용되지 않거나 범위를 벗어난다는 것을 증명하므로 삭제합니다.

이름이나 의도에서 기본값, 권한, 정책, 시간 초과 동작 또는 안전 태세를 추론하지 마십시오. 확인하십시오.

4. 진실 출처 찾기

동작에 민감한 각 주장에 대해 가장 가까운 권위 있는 출처를 사용합니다:

• 구성 필드의 경우 공개 스키마, 플러그인 매니페스트, 생성된 구성 문서 또는 내보낸 타입.
• 명령 및 플래그의 경우 CLI 구현, 슬래시 명령 핸들러, 도움말 텍스트 및 명령 테스트.
• 라이프사이클, 대기열, 권한, 폴백, 시간 초과 및 공급자 동작의 경우 런타임 소스 및 테스트.
• API 및 플러그인 표면의 경우 프로토콜 문서, SDK 퍼사드 및 계약 테스트.
• 대상이 순전히 개념적인 경우가 아니라면 기존 문서는 보조 증거로만 사용합니다.

페이지가 참조를 약속하는 경우, 해당 테이블을 스키마, 매니페스트, CLI 도움말, 생성된 문서 또는 내보낸 타입과 비교합니다. 누락된 공개 필드, 기본값, 우선 순위 규칙, 상한 또는 부작용은 정확성 버그입니다.

5. 이동된 자료 계획

대상 페이지에서 세부 정보를 이동할 때, 편집 전에 대상을 기록합니다:

• 기존 페이지: 페이지 이름과 섹션을 지정합니다.
• 새 페이지: 페이지 유형, 슬러그, 제목, 프론트매터 요약, doc-schema-version: 1, read_when 힌트를 선택합니다.
• 대상 페이지: 간단한 요약을 유지하고 독자가 더 깊은 세부 정보가 필요한 지점에서 링크를 제공합니다.

중복된 진실을 피하십시오. 동일한 계약이 여러 곳에 나타나는 경우, 하나의 표준 페이지를 선택하고 링크합니다.

6. 재작성

다음 순서로 다시 작성합니다:

1. 첫 화면에서 독자가 할 수 있는 작업과 이 페이지가 존재하는 이유를 설명합니다.
2. 권장 경로를 대안보다 먼저 배치합니다.
3. 기본 흐름에 의사 결정 및 일반적인 운영 세부 정보만 유지합니다.
4. 전체 표와 드문 세부 정보를 계획된 참조 페이지로 이동합니다.
5. 독자가 명령, 구성 경로, 하네스, 플러그인, 공급자 또는 참조를 선택하는 데 도움이 되는 간결한 라우팅 테이블을 유지합니다.
6. 내부 추측이 아닌 관찰 가능한 증상에서 문제 해결을 추가합니다.
7. 관련 개념, 가이드, 참조, 진단 및 인접 도구에 링크합니다.

리팩터링이 마이그레이션, 생성 또는 실질적으로 다시 작성하는 모든 문서 페이지의 YAML 프론트매터에 doc-schema-version: 1을 추가합니다. 이는 docs.json 또는 기타 비페이지 메타데이터가 아닌 문서 페이지 파일에만 적용합니다. 마이그레이션된 페이지가 생성된 경우, 생성기를 업데이트하여 생성된 출력을 수동 편집하는 대신 재생성 시 마커를 유지하도록 합니다.

사용자가 초안을 명시적으로 요청하지 않는 한 "TODO", "TBD" 또는 "see docs"와 같은 자리 표시자를 남기지 마십시오.

7. 이전 및 이후 비교

편집 후 이전 및 새 페이지를 비교합니다:

• 모든 동작에 민감한 사실이 유지, 이동 또는 소스 기반 이유로 의도적으로 삭제되었는지 확인합니다.
• 기본 페이지가 여전히 80/20 시나리오를 처음부터 끝까지 다루는지 확인합니다.
• 참조 페이지가 주장하는 범위에 대해 여전히 전체를 다루는지 확인합니다.
• 대상 페이지의 링크가 이동된 세부 정보에 도달하는지 확인합니다.
• 제목이 안정적이고 검색 가능하며 행동 지향적인지 확인합니다.

리팩터링이 관련 자료를 의도적으로 제거하는 경우, 최종 보고서에 해당 자료가 이동된 위치 또는 제거된 이유를 명시합니다.

8. 검증

영향을 받은 표면에 대해 가장 작은 신뢰할 수 있는 문서 검사를 실행합니다:

• pnpm docs:list
• git diff --check -- <touched-files>
• 타겟 pnpm exec oxfmt --check --threads=1 <touched-files>
• pnpm docs:check-mdx
• pnpm docs:check-links
• 스키마, 생성된 구성 문서, API 문서 또는 생성된 기준선이 수정될 때 생성된 문서 검사

가능하면 페이지의 명령과 예제를 실행합니다. 동작에 민감한 주장을 확인할 수 없는 경우, 주장을 제거하거나 진행 중인 보고서에 불확실성을 표시하거나 누락된 소스를 요청합니다.

최종 보고서

보고:

• 대상 페이지에서 변경된 사항.
• 이동된 세부 정보 및 대상 페이지.
• 동작에 민감한 주장을 뒷받침한 진실 출처 확인.
• 실행된 검증 및 관련 없는 이유로 실패한 사항.

긴 재작성 일기를 포함하지 마십시오. 남은 위험이 있는 경우에만 그 내용을 먼저 제시하십시오.