brmdias/best-practice

최적 사례 문서화 스킬(Best Practice Documentation Skill)

TAM 지식 베이스에서 최적 사례 문서화의 전체 워크플로우를 자동화하여, 수동 작업 2-4시간을 10-15분으로 단축합니다.

사용법

/best-practice <topic-name>
/bp <topic-name>

예시:

• /bp webhook-timeout-patterns
• /best-practice runner-disk-management
• /bp ansible-integration-patterns

이 스킬의 기능

완전한 최적 사례 문서화 워크플로우를 실행합니다:

1. 유효성 검사 및 기존 항목 확인 - 중복 방지, 업데이트 처리
2. 지식 베이스 조사 - 유사한 조사, 최적 사례, 고객 사례 검색
3. 문서 탐색 - 공식 가이드 및 버전 정보 검색
4. 제품 코드 검색 - 기술적 세부 사항 및 기본값 확인(해당 시)
5. GitHub 검색 - 커뮤니티 이슈, 버그, 기능 요청 검색
6. Jira 검색 - 내부 개발 티켓 및 수정 버전 파악
7. 커뮤니티 검색 - 필요 시 외부 소스를 WebFetch(선택 사항)
8. 결과 종합 - 사용자 확인을 위한 연구 요약 제시
9. 문서 생성 - TEMPLATE.md 구조에 따라 최적 사례 문서 생성
10. INDEX.md 업데이트 - 카테고리, 알파벳순 표, 빠른 참조에 추가
11. 완료 보고 - 다음 단계를 포함한 종합 요약 제공

지침

이 스킬이 호출되면 다음 단계를 따르세요:

1단계: 인수 파싱 및 유효성 검사

인수에서 주제 이름을 추출합니다:

• 필수: 주제 이름(예: "webhook-timeout-patterns")
• 아직 kebab-case가 아니라면 변환합니다.
• 주제가 80자를 초과하면 경고: "주제가 너무 광범위해 보입니다. 분할하는 것이 좋습니다?"

주제가 제공되지 않은 경우:

• 오류: "사용법: /best-practice "
• 예시 표시

2단계: 기존 최적 사례 확인

비슷한 이름의 기존 최적 사례를 검색합니다:

Glob pattern="*${keywords}*" path="best-practices/"

결정 로직:

• 정확히 일치: 사용자에게 질문: "최적 사례가 <file>에 존재합니다. (1) 기존 항목 업데이트, (2) 다른 초점으로 새로 생성, (3) 취소?"
• 부분 일치: 목록 표시 후 질문: "유사한 항목 발견: <files>. (1) 하나 업데이트, (2) 새로 생성, (3) 취소?"
• 일치 항목 없음: 생성 진행

사용자가 업데이트를 선택하면, 나중에 편집(Edit) 대신 쓰기(Write)를 위해 파일 이름을 기록합니다.

3단계: 지식 베이스 검색

주제 이름에서 검색 키워드를 추출합니다(하이픈 제거, 용어로 분할).

최적 사례 검색:

Grep pattern="<keywords>" path="best-practices/" output_mode="content" -C 3 head_limit=50

조사 검색:

Grep pattern="<keywords>" path="investigations/" output_mode="content" -C 3 head_limit=50

고객 프로필 검색(해당 시):

Grep pattern="<keywords>" path="customers/" output_mode="files_with_matches"

고객 프로필이 발견되면, 컨텍스트 파악을 위해 읽습니다.

수집 및 기록:

• 관련 최적 사례("관련 최적 사례" 섹션용)
• 조사 예시("실제 사례" 섹션용)
• 유사 문서의 일반적인 태그(메타데이터용)
• 해당 시 고객 컨텍스트

4단계: 공식 문서 검색

Grep pattern="<keywords>" path="repositories/docs/" output_mode="content" -C 2 head_limit=30

수집 및 기록:

• 공식 가이드 및 권장 사항
• 버전별 정보
• 구성 참조 및 옵션
• 알려진 제한 사항 또는 주의 사항

5단계: 제품 코드 검색(조건부)

검색 시기:

• 주제가 특정 기능 동작과 관련된 경우
• 기본 구성 값이 필요한 경우
• 성능 특성 이해가 필요한 경우
• 기술적 제약 확인이 필요한 경우

Grep pattern="<component|class>" path="repositories/rundeckpro/" output_mode="content" head_limit=30

수집 및 기록:

• 기본 구성 값
• 구현 세부 사항 및 동작
• 기술적 제약 또는 한계
• 버전별 로직

6단계: GitHub 이슈 검색(Runlayer 커넥터 이용)

Runlayer 커넥터를 통해 GitHub를 쿼리합니다. 이 환경에서는 gh CLI를 사용할 수 없습니다. search_tools를 호출하여 GitHub 이슈 검색 도구를 찾은 후, execute_tool을 호출하여 rundeck/rundeck 및 rundeckpro/rundeckpro에서 <keywords>에 대해 열린 이슈와 닫힌 이슈를 검색합니다. gh 셸 명령을 사용하지 마십시오.

수집 및 기록:

• 알려진 이슈 또는 버그
• 기능 요청 및 커뮤니티 피드백
• 해결 방법 및 커뮤니티 솔루션
• 인용을 위한 이슈 번호

GitHub 커넥터를 사용할 수 없으면 이를 기록하고 계속 진행합니다.

7단계: Jira RUN 프로젝트 검색(Runlayer 커넥터 이용)

Runlayer 커넥터를 통해 Jira를 쿼리합니다. search_tools를 호출하여 Jira 이슈 검색 도구를 찾은 후, 반환된 정확한 tool_name과 인수를 사용하여 execute_tool을 호출합니다. mcp__atlassian__* 도구를 직접 호출하지 마십시오. 다음에 해당하는 매개변수를 사용하십시오:

jql: "project=RUN AND (summary ~ \"<keywords>\" OR description ~ \"<keywords>\") ORDER BY updated DESC"
maxResults: 15

수집 및 기록:

• 내부 개발 티켓
• 수정 버전 및 릴리스 정보
• 개발 상태 및 컨텍스트
• 인용을 위한 Jira 키(RUN-XXXX)

오류 처리: Jira 커넥터를 사용할 수 없으면 "Jira 검색 불가"를 기록하고 계속 진행합니다.

8단계: 커뮤니티 검색(선택 사항/필요 시)

트리거 조건:

• 3-7단계에서 관련 소스를 3개 미만으로 찾은 경우
• 문서화가 잘 되지 않은 새롭거나 떠오르는 패턴인 경우
• 사용자가 더 광범위한 연구를 요청한 경우

WebFetch with parameters:
  url: "https://groups.google.com/g/rundeck-discuss/search?q=<keywords>"
  prompt: "<topic>에 대한 토론을 찾습니다. 추출 항목: 보고된 문제, 제안된 솔루션, 권장되는 패턴, 일반적인 이슈"

수집 및 기록:

• 커뮤니티 솔루션 및 패턴
• 일반적인 함정 및 이슈
• 구현 변형
• 중요: 검증되지 않은 주장은 표시하고, 공식 문서와 대조하여 확인합니다.

9단계: 결과 종합 및 사용자 확인

모든 연구 결과를 분석합니다:

1. 소스 간 패턴 식별
2. 권장 사항 결정: 기본 접근 방식 및 근거 제시
3. 대안 식별: 다른 접근 방식 및 기본 방식을 선호하는 이유
4. 구현 추출: 코드 예제와 함께 단계별 가이드
5. 이점 및 절충점 문서화
6. 메타데이터 선택:
   • 제품 영역: 다음 카테고리 중에서 결정:
     • 작업 설계 및 오케스트레이션
     • 노드 관리 및 타겟팅
     • 보안 및 접근 제어
     • 성능 및 확장
     • 통합 및 웹훅
     • 아키텍처 및 배포
     • 문서 및 유지 관리
   • 적용 버전: Jira/문서에서 가져옴(구체적으로 "Rundeck 5.6.0+" 또는 보수적으로 "모든 버전")
   • 태그: 유사한 BP의 기존 분류법 사용(3단계에서 찾은 태그 스캔), 최대 3-8개 태그

사용자에게 연구 요약 제시:

# 연구 요약: <topic-name>

## 발견된 소스
- 지식 베이스: X개 조사, Y개 최적 사례
- 문서: N페이지
- GitHub: P개 이슈
- Jira: Q개 티켓
- 커뮤니티: [검색한 경우]

## 권장 접근 방식
[연구 기반 기본 권장 사항에 대한 1-2단락 요약]

## 식별된 주요 패턴
- [연구에서 나온 패턴 1]
- [연구에서 나온 패턴 2]
- [연구에서 나온 패턴 3]

## 제안된 메타데이터
- **제품 영역:** [결정된 카테고리]
- **적용 버전:** [연구에서 나온 버전]
- **태그:** #tag1 #tag2 #tag3 [유사한 BP에서]

## 품질 검사
- ✓ [X]개 소스 발견(최소 4개 권장)
- ✓ [Y]개 코드/설정 예제 사용 가능
- ✓ [Z]개 실제 사례 발견

문서를 생성할 준비가 되었습니까?

사용자 확인을 기다립니다. 사용자는 다음을 수행할 수 있습니다:

• 확인하고 진행
• 메타데이터 또는 접근 방식 변경 요청
• 추가 연구 요청
• 워크플로우 취소

사용자 확인 없이 생성 단계로 진행하지 마십시오.

10단계: 최적 사례 문서 생성

사용자가 확인하면 문서를 생성합니다:

1. 참조용 템플릿 읽기:

Read file_path="best-practices/TEMPLATE.md"

2. 조사된 콘텐츠로 모든 섹션 채우기:

헤더(1-6행):

# [단어의 첫 글자를 대문자로 바꾼 주제 이름]

**마지막 업데이트:** 2026-04-20
**제품 영역:** [9단계에서]
**적용 버전:** [9단계에서]
**태그:** #tag1 #tag2 #tag3 [9단계에서]

---

사용 사례 / 시나리오:

• 언제 이 내용이 필요한지 설명(조사 및 문서 기반)
• 어떤 문제를 해결하는가?
• 어떤 시나리오에 적합한가?

권장 사항:

• 명확하고 실행 가능한 지침("무엇을 해야 하는지")
• 종합한 기본 접근 방식
• 여러 옵션이 있는 경우 표를 포함할 수 있음

구현:

• 단계별 방법
• 해당 시 여러 패턴(패턴 1, 패턴 2 등)
• 문서 및 코드 연구에서 가져온 코드 예제

# 실제 YAML/설정 예제 포함
# 연구에서 찾은 코드 스니펫 사용

이것이 효과적인 이유:

• 코드 + 문서 연구 기반 기술적 설명
• 기본 원리 또는 메커니즘
• 이 접근 방식이 효과적인 이유

이점:

• 연구 결과의 번호 매기기 목록
• 구체적인 장점(성능, 보안, 유지 관리 용이성 등)
• 가능하면 수치화

절충점 / 주의 사항:

• 연구에서 식별된 제한 사항
• 성능 고려 사항
• 적용되지 않을 수 있는 상황
• ⚠️ 상충되는 정보가 발견되면 표시

고려된 대안:

• 연구에서 찾은 다른 접근 방식
• 권장 접근 방식이 선호되는 이유
• 대안이 더 나을 수 있는 경우

실제 사례:

• 조사 링크: [고객/사례](../investigations/YYYY-MM-DD-description.md)
• 없는 경우: "아직 문서화된 조사가 없습니다. 이 모범 사례는 [공식 문서/코드 분석/커뮤니티 패턴]을 기반으로 합니다."

관련 최적 사례:

• KB 검색에서 관련 문서 링크
• 형식: [제목](./filename.md) - 간단한 설명

공식 문서:

• 문서 저장소 파일 링크
• 번호별 GitHub 이슈
• 키별 Jira 티켓
• 공식 웹사이트 링크

3. 작성 전 품질 검사:

• ✓ 4개 메타데이터 필드 모두 채워짐
• ✓ 기존 분류의 3-8개 태그
• ✓ 모든 템플릿 섹션 존재
• ✓ 최소 1개의 코드/설정 예제
• ✓ 최소 2개의 인용된 소스
• ✓ 올바른 마크다운 형식

4. 문서 작성:

새로 만드는 경우:

Write file_path="best-practices/<kebab-topic-name>.md" content="<generated-content>"

기존 문서를 업데이트하는 경우(2단계에서):

Edit file_path="best-practices/<existing-filename>.md"

구조를 유지하면서 관련 섹션을 업데이트합니다.

11단계: INDEX.md 업데이트

1. 현재 INDEX 읽기:

Read file_path="best-practices/INDEX.md"

2. 기본 카테고리 결정 (다음 옵션에서 정확히 이모지를 사용):

   • 🎯 작업 설계 및 오케스트레이션
   • 🖥️ 노드 관리 및 타겟팅
   • 🔐 보안 및 접근 제어
   • 📊 성능 및 확장
   • 🔗 통합 및 웹훅
   • 🏗️ 아키텍처 및 배포
   • 📝 문서 및 유지 관리

3. 편집 도구를 사용하여 세 개 섹션 업데이트:

a) 카테고리 섹션: 해당 카테고리(예: "### 🎯 작업 설계 및 오케스트레이션")를 찾아 항목을 추가합니다:

- [제목](./filename.md) - 한 줄 설명 #tag1 #tag2 #tag3

카테고리 내에서 알파벳순으로 삽입합니다.

b) 모든 최적 사례(알파벳순) 표: 올바른 알파벳순 위치를 찾아 삽입합니다:

| [제목](./filename.md) | 카테고리 [& 보조 카테고리, 해당 시] | 2026-04-20 | [관련 사례 또는 "N/A"] |

c) 사용 사례별 빠른 참조 섹션: 일반적인 사용 사례를 반영하는 2-4개의 "다음이 필요합니다..." 항목을 추가합니다:

- **...특정 문제/작업** → [제목](./filename.md)

알파벳순으로 정렬합니다.

4. "마지막 업데이트" 날짜 업데이트: 상단의 날짜를 변경합니다:

**마지막 업데이트:** 2026-04-20

5. 편집 도구로 업데이트 실행: 편집(Edit)을 사용하여 각 변경 사항을 적용합니다(또는 서로 가까이 있으면 결합):

Edit file_path="best-practices/INDEX.md" old_string="<existing-text>" new_string="<updated-text>"

12단계: 완료 보고

종합적인 완료 요약 제공:

✅ 최적 사례가 성공적으로 생성되었습니다!

## 문서 세부 정보
**제목:** [전체 제목]
**파일:** best-practices/<filename>.md
**카테고리:** [기본 카테고리]
**태그:** #tag1 #tag2 #tag3

## 연구 요약
- 지식 베이스: X개 조사, Y개 최적 사례
- 문서: N페이지
- GitHub: P개 이슈
- Jira: Q개 티켓
- 커뮤니티: [검색한 경우]
- **총 소스:** [개수]

## 완료된 문서 섹션
✓ 사용 사례 / 시나리오
✓ [개수]개 패턴이 포함된 권장 사항
✓ [개수]개 코드 예제가 포함된 구현
✓ 이것이 효과적인 이유
✓ [개수]개의 나열된 이점
✓ [개수]개의 문서화된 절충점
✓ [개수]개의 고려된 대안
✓ 실제 사례: [링크 또는 "문서화 보류 중"]
✓ [개수]개의 연결된 관련 최적 사례
✓ [개수]개의 공식 문서 참조

## INDEX.md 업데이트됨
✓ [카테고리 이름]에 추가됨
✓ 알파벳순 표에 추가됨([N]행)
✓ [개수]개의 빠른 참조 항목 추가됨
✓ "마지막 업데이트" 날짜 업데이트됨

## 다음 단계
1. best-practices/<filename>.md에서 문서 검토
2. 해당 시 샌드박스에서 구현 테스트
3. 팀과 공유: `/share-kb "<title>" best-practices/<filename>.md`
4. 해당 시 관련 고객 프로필에서 링크

생성이 아닌 업데이트인 경우:

✅ 최적 사례가 성공적으로 업데이트되었습니다!

## 업데이트된 문서
**제목:** [전체 제목]
**파일:** best-practices/<filename>.md
[업데이트 시나리오에 맞게 조정된 나머지 요약]

품질 지침

연구 품질

• 최소 4가지 소스 카테고리(KB, 문서, 코드, 외부 추적기) 검색
• 코드/문서 참조에 대한 특정 파일 경로 인용
• 번호로 GitHub 이슈 연결(#1234)
• 키로 Jira 티켓 연결(RUN-1234)
• 공식 소스와 대조하여 커뮤니티 주장 확인
• 검증되지 않았거나 상충되는 정보 표시

문서 품질

• 명확성: 각 섹션은 즉시 실행 가능하거나 유익해야 함
• 완전성: 모든 템플릿 섹션 채움(TODO 없음)
• 증거 기반: 모든 권장 사항은 소스에 의해 뒷받침됨
• 실용성: 산문뿐만 아니라 실제 코드/설정 예제 포함
• 정직함: 절충점 및 주의 사항이 명확하게 명시됨

...

[번역을 위해 잘림]