Copyright (C) 2026 ZionXiaoxiSuOGLocGo SPDX-License-Identifier: GPL-3.0-or-later
project-docs
세 가지 문서로 구성된 프로젝트 지식 시스템을 생성하고 유지 관리합니다. project-onboard에서 감지하는 모든 프로젝트 유형을 지원하며, 프로젝트 유형에 따라 올바른 템플릿을 자동 선택합니다.
세 가지 문서 시스템
| 파일 | 목적 | 업데이트 빈도 |
|---|---|---|
AGENTS.md | 프로젝트 개요: 식별 정보, 디렉터리 구조, 클래스 아키텍처, 진입점, 의존성, 참고 사항 | 마일스톤당 (~3-5개 새 파일/클래스) |
PROJECT_STATE.md | 살아있는 문서: 전체 클래스/소스 목록 (매개변수 포함), 설정, 모듈 맵, 시스템 흐름, 완료/할 일 목록 | 세션 종료 시마다 |
DEVLOG.md | 개발 로그: 타임라인 항목 — 수행한 작업, 이유, 배운 점 | 하루 또는 기능 마일스톤당 |
업데이트 트리거, 내용 경계 및 일관성 검사에 대한 자세한 규칙은 maintenance-spec.md를 참조하세요.
템플릿 선택
템플릿은 project-onboard 규칙 팩과 동일한 자동 검색 패턴을 따릅니다. 스킬은 templates/<type>/PROJECT_STATE.md.tmpl을 로드하려고 시도하며, 여기서 <type>은 AGENTS.md 기본 정보의 Type 값을 소문자로 변환한 것입니다. 유형별 템플릿이 없으면 templates/PROJECT_STATE.md.tmpl로 폴백합니다.
templates/<type>/PROJECT_STATE.md.tmpl 존재? → 사용
없음 → templates/PROJECT_STATE.md.tmpl 사용 (일반 폴백)
새 엔진이나 프레임워크 지원 추가: templates/<type>/PROJECT_STATE.md.tmpl을 생성하세요. 코드 변경이 필요 없습니다. 스킬이 자동으로 발견합니다.
모든 유형은 templates/DEVLOG.md.tmpl을 공유합니다 (프로젝트 유형에 구애받지 않음).
AGENTS.md → PROJECT_STATE.md 필드 매핑
PROJECT_STATE.md를 AGENTS.md 데이터로 미리 채울 때 다음 매핑을 사용하세요.
| AGENTS.md 섹션 | AGENTS.md 필드 | STATE 템플릿 섹션 | STATE 플레이스홀더 |
|---|---|---|---|
| 기본 정보 | Type, Language, Framework/Engine, Key Dependencies | §1 프로젝트 식별 | {{PROJECT_TYPE}}, {{LANGUAGE}}, {{FRAMEWORK}}, {{KEY_DEPENDENCIES}} |
| 기본 정보 | Engine (게임 프로젝트의 경우) | §1 프로젝트 식별 | {{ENGINE_VERSION}} |
| 디렉터리 구조 | 디렉터리 및 설명 | §2 디렉터리 구조 | {{DIRECTORY_TREE}} (일반) 또는 Source/{{MODULE_NAME}}/... (UE) |
| 핵심 아키텍처 | 주요 파일/클래스 및 역할 | §3 소스/스크립트 스펙트럼 | {{CLASS_NAME}}, {{RESPONSIBILITY}}, {{FILE_NAME}} |
| 의존성 | 패키지 요약 | §4 설정 / §7 의존성 | {{CONFIG_KEY}}, {{DEP_NAME}} (문맥에 따라 다름) |
| 빌드 및 실행 | 빌드/테스트 명령어 | §9 빌드 및 실행 | {{BUILD_CMD}}, {{RUN_CMD}}, {{TEST_CMD}} |
| 진입점 | 시작 파일/씬 및 역할 | §1 프로젝트 식별 (모듈) | {{MODULE_NAME}} |
영어가 아닌 출력: 섹션 헤더, 레이블 및 플레이스홀더 설명은 번역하되 {{PLACEHOLDER}} 마커는 그대로 유지하세요.
이 스킬을 사용하는 경우
- 사용자가 "init project docs" / "建立文档体系" / "project-docs"라고 말할 때
- 새 프로젝트에 PROJECT_STATE.md 및 DEVLOG.md가 필요할 때
- 기존 프로젝트에 AGENTS.md는 있지만 다른 두 문서가 누락되었을 때
- 사용자가 세션 후 프로젝트 상태 업데이트를 요청할 때
워크플로
1. 초기화 (새 프로젝트 / 누락된 문서)
-
문서를 생성할 언어를 사용자에게 묻습니다. 사용자가 건너뛰거나 "상관없다"고 하면 기본값은 영어입니다. LLM이 출력할 수 있는 모든 언어가 지원됩니다. 에이전트가 생성 시 번역을 처리합니다:
"프로젝트 문서는 어떤 언어로 작성할까요? 기본값: 영어. LLM이 출력할 수 있는 모든 언어가 지원됩니다."
-
AGENTS.md가 존재하는지 확인합니다.- 없는 경우: 먼저
project-onboard스킬을 실행하여 AGENTS.md를 생성하도록 제안합니다. 여기서 중단합니다. - 있는 경우: AGENTS.md를 읽고 다음을 추출합니다:
- 프로젝트 이름
- Type (기본 정보에서 — 예: "unreal", "unity", "nodejs", "python")
- 핵심 아키텍처 (클래스, 파일, 역할)
- 없는 경우: 먼저
-
템플릿 감지: 추출된 Type(소문자)을 기반으로 유형별 템플릿을 로드하려고 시도합니다. 일치하는 항목이 없으면 일반 템플릿으로 폴백합니다:
- 먼저
templates/<type>/PROJECT_STATE.md.tmpl시도 - 해당 파일이 없으면
templates/PROJECT_STATE.md.tmpl사용 (일반)
- 먼저
-
선택한 템플릿에서
PROJECT_STATE.md생성:- 위 필드 매핑 테이블을 사용하여 AGENTS.md 데이터로 §1-§3을 미리 채웁니다.
- 나머지 섹션은 향후 업데이트를 위해 플레이스홀더 구조를 그대로 둡니다.
-
templates/DEVLOG.md.tmpl에서DEVLOG.md생성:- 프로젝트 이름을 채웁니다.
- 첫 번째 개발 로그 항목을 위해 항목 템플릿을 준비 상태로 둡니다.
-
AGENTS.md의 맨 위,# 프로젝트 이름제목 줄 바로 다음 (그러나 나머지 콘텐츠 앞)에 다음 블록을 추가합니다:## 먼저 읽어주세요 1. `PROJECT_STATE.md` 읽기 — 현재 작업 상태 및 할 일 항목 (§10) 2. `DEVLOG.md` 읽기 — 최근 개발 기록 --- -
무엇이 생성되었는지, 어떤 템플릿이 사용되었는지, 어떤 언어인지 보고합니다.
2. 업데이트 (기존 문서)
PROJECT_STATE.md읽기 → §10 할 일 목록 식별- 사용자에게 완료된 작업 / 변경된 사항 질문
- 영향을 받는 섹션 업데이트:
- §1-§2: 프로젝트 식별 정보 또는 디렉터리 구조가 변경된 경우
- §3: 새 클래스, 파일 또는 주요 멤버
- §4: 설정 변경 (블루프린트 속성, 프리팹 설정 또는 일반 설정)
- §5: 입력 바인딩, 액션 매핑 또는 모듈/패키지 변경
- §6: 시스템 로직, 아키텍처 흐름 또는 게임 시스템 변경
- §7: 씬/레벨 설정 또는 외부 서비스 변경
- §8: 숫자 매개변수 변경
- §9: 빌드 문제, 새 컴파일 오류 또는 명령어 변경
- §10: 항상 업데이트 — 완료 목록, 할 일 목록, 알려진 문제
DEVLOG.md에 항목 추가 (maintenance-spec.md형식에 따라)- 아키텍처가 변경된 경우 (새 클래스, 플러그인, 디렉터리) →
AGENTS.md업데이트
3. 일관성 검사
업데이트 후 다음을 확인합니다:
- AGENTS.md와 PROJECT_STATE.md 간에 중복 데이터 없음 (아키텍처 개요와 매개변수 세부 정보 분리)
- AGENTS.md 디렉터리 구조 항목 모두 PROJECT_STATE.md에 대응 항목 있음
- PROJECT_STATE.md §8 매개변수 값이 실제 소스 기본값과 일치 (예:
.h기본값, 설정 파일 값, BP CDO 재정의) - PROJECT_STATE.md §10 할 일 목록이 DEVLOG.md 최신 항목과 모순되지 않음 (DEVLOG에서 완료되었다고 하면 STATE도 일치해야 함)
- 세 문서 간에 중복 정보 없음 (하나의 사실 = 하나의 위치)
템플릿
템플릿은 프로젝트 유형별로 자동 검색되며 하드코딩된 매핑 테이블이 없습니다. 디렉터리는 project-onboard 참조 구조를 미러링합니다:
templates/
├── DEVLOG.md.tmpl ← 모든 유형 (일반)
├── PROJECT_STATE.md.tmpl ← 폴백 (일반)
├── unreal/PROJECT_STATE.md.tmpl ← Unreal Engine
└── unity/PROJECT_STATE.md.tmpl ← Unity
templates/<type>/PROJECT_STATE.md.tmpl 파일은 선택 사항입니다. 스킬은 AGENTS.md Type과 일치하는 파일을 로드하려고 시도하며, 없으면 루트 일반 템플릿을 사용합니다.
새 유형 추가: 유형별 섹션이 포함된 templates/<type>/PROJECT_STATE.md.tmpl을 생성하세요. 스킬은 다음 실행 시 이를 발견합니다. 코드 변경이 전혀 필요 없습니다.
규칙
- 기존 파일을 절대 덮어쓰지 마십시오. 문서가 존재하면 그 자리에서 업데이트합니다.
- 내용 경계를 존중하십시오: AGENTS.md = 아키텍처 개요. PROJECT_STATE.md = 매개변수 세부 정보 + 상태. DEVLOG.md = 타임라인 서술.
- 유지 관리 사양: 정확한 업데이트 트리거, 내용 경계 및 금지된 관행은
maintenance-spec.md를 참조하세요. - STATE/DEVLOG의 프로젝트별 경로/클래스 이름은 예상됩니다. 이들은 프로젝트 문서이며 재사용 가능한 매뉴얼이 아닙니다.