AI Backend Documentation Skills

백엔드 시스템 설계 문서를 자동으로 생성하기 위한 Agent Skills 모음입니다.

Agent Skills 오픈 표준 형식을 따르며, Claude Code, OpenAI Codex, Cursor, GitHub Copilot 등 주요 AI 코딩 에이전트에서 사용할 수 있습니다.

이 스킬들은 실제로 KOPLE App 프로젝트의 백엔드 설계 문서를 작성하는 과정에서 사용되었습니다.

---

Skills

kople-context

KOPLE 프로젝트의 이중 서버/DB 아키텍처, Clerk 기반 인증 체계 배경지식입니다. LLM이 기본적으로 알지 못하는 KOPLE 고유의 시스템 구조(Web DB / App DB 분리, Webhook Event-driven 등)를 제공합니다. 다른 스킬들이 KOPLE 문서를 생성할 때 참조합니다.

sequence-diagram

백엔드 서비스 흐름을 Mermaid sequenceDiagram 형식으로 생성합니다. API 호출 흐름, 인증 흐름, Webhook 이벤트 흐름 등을 문서화합니다. --diff 모드로 main 브랜치 대비 변경점 기반 다이어그램을 생성할 수 있습니다.

architecture-diagram

시스템 컴포넌트 간의 관계를 Mermaid 아키텍처 다이어그램으로 생성합니다. KOPLE의 이중 서버 구조(Web/App 분리, Clerk SSOT) 패턴을 포함합니다. --diff 모드로 아키텍처 변경점을 문서화할 수 있습니다.

api-spec

REST API의 엔드포인트, 요청/응답, 에러 케이스를 포함한 API 명세 문서를 생성합니다. KOPLE의 Clerk JWT 인증 API, Webhook 수신 API 패턴을 지원합니다. --diff 모드로 API 변경점만 문서화할 수 있습니다.

backend-design-doc

10개 섹션(배경, 설계 원칙, 아키텍처, 데이터 모델, 보안, 장애 대응 등)으로 구성된 종합 설계 문서를 생성합니다. KOPLE 설계 원칙(SSOT, Event-driven, DB 분리 등) 템플릿을 포함합니다.

auth-flow

Clerk 기반 인증/인가 흐름(로그인, 회원가입, 탈퇴, 정지)을 Mermaid 시퀀스 다이어그램과 함께 문서화합니다. KOPLE의 이중 서버 환경에서 JWT/JWKS 검증, Webhook 기반 사용자 상태 동기화 구조를 반영합니다.

---

디렉토리 구조

skills/
├── kople-context/            # KOPLE 프로젝트 배경지식
│   ├── SKILL.md
│   └── references/
│       └── kople-architecture.md
├── sequence-diagram/         # 시퀀스 다이어그램 생성
│   └── SKILL.md
├── architecture-diagram/     # 아키텍처 다이어그램 생성
│   └── SKILL.md
├── api-spec/                 # REST API 명세 생성
│   └── SKILL.md
├── backend-design-doc/       # 백엔드 설계 문서 생성
│   └── SKILL.md
└── auth-flow/                # 인증/인가 흐름 문서 생성
    └── SKILL.md
examples/                     # 스킬 출력 예시

---

왜 만들었나

• 반복적인 설계 문서 작성 자동화
• Mermaid 기반 다이어그램 생성 표준화
• 팀 전체에서 동일한 문서 형식 유지
• LLM이 모르는 프로젝트 고유 컨텍스트(KOPLE 이중 DB 구조 등) 주입
• main 브랜치 대비 변경점 기반 문서 생성

---

사용 예시

시퀀스 다이어그램 생성

KOPLE 로그인 흐름의 시퀀스 다이어그램을 생성해줘

변경점 기반 문서화

main 브랜치와 비교해서 변경된 API 명세를 문서화해줘

아키텍처 다이어그램 생성

KOPLE 시스템의 이중 서버/DB 아키텍처 다이어그램을 생성해줘

인증 흐름 문서화

KOPLE 회원 탈퇴 시 Webhook 기반 Event-driven 흐름을 문서화해줘

---

호환 도구

Agent Skills 오픈 표준 기반으로, 다음 도구에서 사용 가능합니다:

Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Windsurf, Gemini CLI, Aider, Kilo Code, OpenCode, Augment 등