본문으로 건너뛰기

Team Library Harness 작성 및 확장 가이드

이 문서는 Team Library의 Harness 문서를 처음 보는 사람도 이해할 수 있게 읽고, 이후에 직접 내용을 추가하거나 확장할 수 있게 돕기 위한 가이드입니다.

즉, 아래 두 가지를 동시에 목표로 합니다.

  • 읽는 사람 입장에서: "이게 무슨 문서인지 이해되게 만들기"
  • 작성하는 사람 입장에서: "다음 내용을 어디에 어떻게 추가해야 하는지 알 수 있게 만들기"

먼저 이해하면 좋은 구조​

Harness 문서는 보통 아래 3단계로 나눠서 보면 편합니다.

1. Meta Harness​

질문:

  • 어떤 문제를 풀기 위한 하네스인가?
  • 어떤 입력과 출력을 상정하는가?
  • 어떤 역할 분리가 필요한가?

대표 문서:

  • Team Library Meta Harness

2. Generated Output​

질문:

  • 실제로 어떤 에이전트와 스킬이 나왔는가?
  • 현재 운영 초안은 어디까지 와 있는가?

대표 문서:

  • Team Library Harness Generated Output

3. Workflow / Template / Ops 연계 문서​

질문:

  • 실제 운영 흐름은 어떻게 되는가?
  • 문서는 어디에 반영하는가?
  • 배포 전후에 무엇을 확인하는가?

대표 문서:

  • Slack 답변을 Team Library 문서로 전환하는 운영 흐름
  • Team Library 도메인 및 HTTPS 배포 가이드

문서를 추가할 때 추천하는 기준​

새 문서를 만들 때는 먼저 아래 질문 중 어디에 해당하는지 보면 좋습니다.

A. 개념 설명 문서인가?​

예:

  • 특정 하네스의 목적 설명
  • 에이전트 역할 설명
  • 문서화 원칙 설명

권장 위치:

  • docs/harness/

B. 실제 운영 절차 문서인가?​

예:

  • Slack 답변을 문서로 바꾸는 절차
  • 게시 승인 흐름
  • 초안 검토 절차

권장 위치:

  • docs/workflows/

C. 배포/서버/도메인/HTTPS 같은 운영 문서인가?​

예:

  • nginx 설정
  • 정적 사이트 배포
  • 도메인 연결

권장 위치:

  • docs/ops/

D. 요청 양식이나 체크리스트인가?​

예:

  • 문서화 요청 템플릿
  • 검토 체크리스트
  • 게시 전 확인표

권장 위치:

  • docs/templates/
  • 또는 성격에 따라 docs/homepage/, docs/publishing/

문서를 친절하게 쓰는 기본 원칙​

다른 사람이 이해하기 쉬운 문서로 만들려면 아래 원칙을 권장합니다.

1. 첫 문단에서 정체를 설명하기​

문서를 열자마자 아래 3가지를 알 수 있어야 합니다.

  • 이 문서는 무엇인가?
  • 왜 필요한가?
  • 누구를 위한 문서인가?

2. 전문 용어는 바로 풀어쓰기​

예를 들어 meta harness, generated output, publisher-planner 같은 표현은 처음 보는 사람도 이해할 수 있게 한 번은 쉬운 말로 설명하는 것이 좋습니다.

3. 추상 설명 뒤에는 운영 예시 붙이기​

설명만 있으면 멈추기 쉽습니다. 가능하면 아래 중 하나를 같이 넣는 것이 좋습니다.

  • 실제 요청 예시
  • 실제 경로 예시
  • 실제 파일 구조 예시
  • 실제 배포 명령 예시

4. "무엇을 안 하는지"도 적기​

문서는 범위를 분명히 할수록 오해가 줄어듭니다. 예:

  • 자동 게시까지 하지 않음
  • 사람 승인 없이 배포하지 않음
  • 민감정보는 자동 공개하지 않음

5. 다음 문서를 연결해주기​

읽는 사람이 막히지 않도록, 문서 하단에는 보통 아래를 추가하는 것이 좋습니다.

  • 같이 보면 좋은 문서
  • 다음 단계 제안
  • 관련 경로

문서 템플릿 추천​

새 Harness 문서를 추가할 때는 아래 구조를 기본으로 쓰면 무난합니다.

# 제목

한 줄 요약

## 목적
## 왜 필요한가
## 적용 범위
## 입력
## 출력
## 주요 역할
## 운영 예시
## 확장 포인트
## 관련 문서

자주 추가하면 좋은 문서 주제​

아래 주제는 Team Library 운영이 커질수록 가치가 높습니다.

  • 문서 검토 체크리스트
  • 민감정보 검토 기준
  • 게시 경로 선택 기준
  • Slack 답변 → 문서 전환 예시 모음
  • 회의록 → 결정사항 문서 변환 예시
  • 주간보고 → 반복 이슈 추출 기준
  • 문서 제목/파일명 규칙
  • 카테고리별 작성 템플릿

실제로 새 문서를 추가하는 방법​

1. 적절한 폴더에 md 파일 생성​

예:

cd /root/.openclaw/workspace/docusaurus-team-library

그리고 성격에 맞는 경로에 문서를 추가합니다.

예:

  • docs/harness/...
  • docs/workflows/...
  • docs/ops/...
  • docs/templates/...

2. front matter 작성​

문서 상단에는 최소한 아래를 넣는 것을 권장합니다.

---
title: 문서 제목
description: 문서 설명
sidebar_position: 1
---

3. sidebar 반영 여부 확인​

사이드바에 직접 등록하는 구조라면 sidebars.ts에 항목을 추가해야 합니다.

현재 Harness 카테고리 예시는 아래와 같습니다.

  • harness/team-library-meta-harness
  • harness/team-library-harness-generated-output

4. 로컬 빌드 확인​

npm run build

5. 배포 전 체크​

  • 링크 깨짐 여부
  • 제목/설명/경로 적절성
  • 문서 위치 적절성
  • 민감정보 포함 여부

추천 추가 문서 후보​

지금 상태에서 바로 추가하면 좋은 문서는 아래와 같습니다.

1. Harness 문서 검토 체크리스트​

  • 문서 공개 범위
  • 민감정보 점검
  • 중복 문서 여부
  • 운영 적용 가능성

2. Team Library 게시 경로 선택 가이드​

  • 이 문서를 docs에 둘지 blog에 둘지
  • workflows와 templates를 어떻게 구분할지

3. Slack 문서화 예시 모음​

  • 잘 정리된 before / after 사례
  • 어떤 질문이 어떤 문서로 바뀌는지 사례화

문서 품질을 높이는 체크포인트​

  • 처음 읽는 사람도 1분 안에 목적을 이해할 수 있는가?
  • 실제 운영자가 따라 할 수 있는 수준으로 구체적인가?
  • 추상적인 설명만 있고 실행 예시가 빠져 있지 않은가?
  • 다음 단계가 연결되어 있는가?
  • 문서 제목만 보고도 용도를 짐작할 수 있는가?

배포 전 권장 절차​

  1. 초안 작성
  2. 내부 검토
  3. npm run build 확인
  4. 필요한 경우 사이드바 반영
  5. 운영자 승인
  6. 정적 파일 배포

한 줄 정리​

이 가이드는 Harness 문서를 읽는 사람에게는 안내서, 작성하는 사람에게는 확장 규칙 역할을 하도록 만든 기준 문서입니다.