| name | sync-docs |
| description | Use this skill when the user asks to synchronize project documentation after implemented changes. Do not trigger for planning-only conversations. |
Sync Docs Skill
세션 작업 완료 후 프로젝트 문서를 docs/에 동기화하는 스킬입니다. OpenAI Codex 워크플로우를 기본으로 하며 특정 벤더 도구에 종속되지 않게 관리합니다.
When to Trigger
이 스킬은 다음 상황에서 실행합니다:
- 세션 종료 시: 사용자가 "문서 동기화", "sync docs", "문서 업데이트" 요청 시
- 주요 작업 완료 후: 아키텍처 변경, 새로운 기능 구현, 중요한 리팩토링 완료 시
- 사용자 요청 시:
sync-docs 스킬 명시 호출(지원 환경) 또는 명시적 요청 시
Documentation Structure
docs/ 디렉토리 구조:
docs/
├── ARCHITECTURE.md # 프로젝트 아키텍처 개요
├── CONVENTIONS.md # 코드 컨벤션 및 패턴
├── MODULES.md # 모듈별 설명 (구현된 모듈만)
└── REQUIREMENTS.md # 요구사항 문서
Sync Scope
/sync-docs 실행 시 동기화 대상:
docs/ - 프로젝트 문서.agents/skills/sync-docs/SKILL.md - 이 스킬 파일 자체AGENTS.md - 문서 진입점(인덱스) 일관성 확인
Workflow
Step 1: 현재 문서 상태 확인
1. docs/ 디렉토리의 기존 문서 파일들 읽기
2. .agents/skills/sync-docs/SKILL.md 읽기
3. 마지막 업데이트 시점 파악
Step 2: 변경 사항 분석
1. 이번 세션에서 수행한 작업 목록 수집 (todowrite로 관리된 TODO와 작업 로그 활용)
2. 변경된 파일들 분석 (git diff 또는 작업 기록)
3. 아키텍처/패턴 변경 사항 식별
4. 실제 구현된 코드 변경만 문서화 대상으로 식별
5. REQUIREMENTS.md 필수 검토: Implementation Details 섹션 업데이트 필요 여부 확인
Step 3: 문서 업데이트
각 문서별 업데이트 기준:
ARCHITECTURE.md
- 새로운 모듈/레이어 구현 시
- 의존성 구조 실제 변경 시
- 주요 컴포넌트 실제 추가/제거 시
- 계획만 있는 경우 업데이트 하지 않음
CONVENTIONS.md
- 새로운 코딩 패턴 실제 도입 시
- 기존 컨벤션 변경 시
- 네이밍 규칙 업데이트 시
MODULES.md
- 새로운 모듈 실제 구현 완료 시에만 추가
- 모듈 책임/역할 실제 변경 시
- 계획(Planned) 상태의 모듈은 절대 추가하지 않음
- 코드 블록 사용 금지
REQUIREMENTS.md (필수 검토)
- 항상 검토 필수: 구현된 기능의 Implementation Details 섹션 업데이트
- 요구사항 분석 완료 시
- 새로운 기능 요구사항 추가 시
- 기존 기능 구현 완료 시 Status 변경 (Planned/In Progress → Done)
- 구현된 컴포넌트 목록 업데이트
- 코드 블록 사용 금지
코드 블록 규칙: 코드 스니펫은 CONVENTIONS.md에만 작성. MODULES.md와 REQUIREMENTS.md는 설명/스펙만 기술.
SKILL.md (이 파일)
- 문서 구조 변경 시
- 워크플로우 변경 시
- 새로운 규칙 추가/삭제 시
Step 4: 검증 및 요약
1. 문서 내용 일관성 검증
2. 마크다운 포맷 검증
3. 변경 사항 요약 출력
4. (선택) 커밋 제안 - 사용자 확인 후
Document Templates
ARCHITECTURE.md Template
# Project Architecture
## Overview
[프로젝트 목적과 핵심 아키텍처 설명]
## Layer Structure
[레이어별 책임과 의존성 방향]
## Tech Stack
[사용 기술 스택과 선택 이유]
---
*Last Updated: YYYY-MM-DD*
CONVENTIONS.md Template
# Code Conventions
## Naming
[네이밍 규칙]
## Architecture Patterns
[사용하는 아키텍처 패턴]
## File Structure
[파일/폴더 구조 규칙]
## Best Practices
[프로젝트별 베스트 프랙티스]
---
*Last Updated: YYYY-MM-DD*
MODULES.md Template
# Module Documentation
## [Module Name]
### Purpose
[모듈의 목적]
### Responsibilities
[모듈의 책임]
### Dependencies
[의존하는 다른 모듈]
### Key Classes/Functions
[주요 클래스/함수 목록]
---
Implementation Notes
DO
- 실제 구현된 코드에 기반한 문서화만 수행
- 코드베이스 분석 후 정확한 정보 기록
- 기존 문서 스타일 유지
- 변경 사항만 업데이트 (전체 재작성 X)
- 날짜 기록 필수
DO NOT
- 추측으로 문서 작성 금지
- 코드 읽지 않고 문서화 금지
- 계획(Planned) 상태를 구현 완료처럼 문서화 금지
- 사용자 확인 없이 커밋 금지
- 존재하지 않는 문서 파일 참조 금지
Integration with Entry Docs
문서 동기화 후 엔트리 문서(AGENTS.md)에 참조가 최신인지 확인:
## External File Loading
CRITICAL: 다음 문서들은 작업 시 참고하세요:
- 아키텍처 이해: @docs/ARCHITECTURE.md
- 코드 컨벤션: @docs/CONVENTIONS.md
- 모듈 설명: @docs/MODULES.md
- 요구사항: @docs/REQUIREMENTS.md
Example Usage
User: 문서 동기화해줘
Agent:
1. docs/ 및 .agents/skills/sync-docs/SKILL.md 확인
2. 이번 세션 작업 분석 (실제 구현된 것만)
3. 관련 문서 업데이트
4. 변경 사항 요약 출력
5. 커밋 여부 확인
Last Updated: 2026-02-13 (Codex 기준 docs/ + .agents/skills 구조로 경로 갱신)
