에이전트 환경 초기화 및 업그레이드 (메타 프로젝트 Init 및 감사)
에이전트 워크플로우를 위해 모든 저장소를 준비하는 자율 스킬입니다. 기존 meta-project 구조가 있는지 자동으로 확인하고, 축적된 데이터의 덮어쓰기를 방지하며, 최신 표준으로 안전하게 업그레이드하거나 처음부터 구조를 부트스트랩합니다.
지속적/기회적 리프레시 원칙에 의존합니다. 메타 지식 조각에 접근할 때, 에이전트는 격차를 메우고 프로젝트에 대한 일관된 비전을 유지해야 합니다.
스킬 호출 시점
- 사용자가 요청하는 경우: "에이전트를 위해 저장소 준비", "메타 프로젝트 초기화", "AGENTS.md 확인", "에이전트 구조 업데이트", "메타 지식 리프레시".
실행 단계
0단계: 기존 메타 프로젝트 환경 확인
쓰기 작업을 수행하기 전에 메타 프로젝트 구성 요소의 존재 여부를 확인합니다:
- 저장소 루트에
AGENTS.md가 있는지 확인합니다. .agents/project_knowledge/및.agents/skills/디렉토리가 있는지 확인합니다.
시나리오 A: 구조 이미 존재 (감사 및 안전 업그레이드 모드)
AGENTS.md 또는 .agents/ 폴더가 저장소에 이미 있는 경우:
- 파괴적 덮어쓰기 금지:
observations.md를 삭제하거나 덮어쓰는 것은 엄격히 금지됩니다. 모든 축적된 관찰 결과는 보존되어야 합니다.- 기존
AGENTS.md의 사용자 정의 불변 조건과 설명을 삭제하는 것은 금지됩니다.
- 표준 준수 감사:
AGENTS.md에 "원칙 및 아키텍처 방향 (North Stars)" 섹션이 있는지 확인합니다. 없으면 서비스 목적과 불변 조건을 수정하지 않고 추가합니다.AGENTS.md에 "접근 + 기회적 리프레시" 링크가 있는 지시 프로토콜이 있는지 확인합니다. 오래된 경우 해당 섹션을 업데이트합니다.boundaries.md에서 글로브 패턴 사용, 데이터 디렉토리 보호 (data/**,*.db), 포맷팅/렌더링 모듈을 Yellow 영역에 할당, Default Deny (Black Zone) 불변 조건의 존재 여부를 확인합니다.observations.md테이블에Category열이 있는지 확인합니다. 레거시 4열 형식을 사용하는 경우 데이터 행을 삭제하지 않고 테이블 헤더를 업데이트합니다..agents/skills/(record-observation,sync-architecture,ground-meta-project)에 있는SKILL.md파일의 최신 상태를 확인합니다.
- 안전한 개선:
- 누락된 슬라이스를 생성합니다 (예:
weak_spots.md가 없는 경우). AGENTS.md의 스킬 레지스트리에 저장소에 대한 새로운 전문 스택 스킬을 추가합니다.
- 누락된 슬라이스를 생성합니다 (예:
- 업그레이드 보고:
- 사용자에게 알립니다: "기존 메타 프로젝트가 감지되었습니다. 축적된 데이터 손실 없이 최신 표준으로 감사 및 업그레이드되었습니다."
시나리오 B: 초기 설정 (클린 스캐폴드 모드)
구조가 없으면 표준 2패스 알고리즘을 실행합니다:
패스 1: 빠른 스캔 및 스켈레톤 생성 (빠르고 고수준)
-
저장소 루트 빠른 검사: 루트 디렉토리를 나열하고 식별합니다:
- 매니페스트:
package.json,pyproject.toml,go.mod,Cargo.toml,requirements.txt,pom.xml,docker-compose.yml. - 코어 디렉토리:
src/,app/,tests/,migrations/,scripts/,data/. - 매핑되지 않은 디렉토리 없음 규칙: 저장소 루트의 모든 최상위 소스 디렉토리를 열거합니다.
.gitignore경로, VCS 메타데이터, 표준 빌드/패키지/테스트 캐시 (.git,node_modules,.venv,venv,dist,build,coverage,__pycache__,.pytest_cache,.idea,.vscode)를 엄격히 필터링합니다. 나머지 모든 최상위 소스 디렉토리는boundaries.md에서 Green, Yellow 또는 Red 영역에 명시적으로 할당되어야 합니다 (매핑되지 않은 디렉토리는 기본적으로 Default Deny / Red Zone에 속합니다). README.md(있는 경우)의 프로젝트 이름, 목적 및 핵심 개념..env.example(있는 경우)의 필수 키 및 종속성.
- 매니페스트:
-
기술 스택 및 핵심 원칙 식별:
- 간결한 스택 문자열을 공식화합니다 (예:
Python 3.12, FastAPI, uv, pytest, Docker). - 2-3개의 기준 방향을 강조합니다 (예: 아키텍처 단순성, 엄격한 타이핑, 데이터 불변성, 오프라인 우선).
- 간결한 스택 문자열을 공식화합니다 (예:
-
디렉토리 구조 생성: 디렉토리 생성:
- .agents/project_knowledge/
- .agents/project_knowledge/archive/
- .agents/skills/record-observation/
- .agents/skills/sync-architecture/
- .agents/skills/ground-meta-project/
- scripts/
-
번들된 메타 프로젝트 스킬 및 런타임 스크립트 배포: 아래 포함된 템플릿에서 SKILL.md 파일을 다음 위치에 작성:
- .agents/skills/record-observation/SKILL.md
- .agents/skills/sync-architecture/SKILL.md
- .agents/skills/ground-meta-project/SKILL.md 저장소 scripts/에 제로 종속성 경계 및 압축 자동화 스크립트 배포:
- scripts/check_boundaries.py (경계 게이트 CLI)
- scripts/compact_memory.py (컨텍스트 로트 실드 및 메모리 컴팩터)
-
초기 지식 슬라이스 초안 생성: .agents/project_knowledge/에 파일 작성:
- observations.md (첫 번째 초기화 행이 있는 5열 테이블; 크로스 플랫폼 명령 예제 사용, 예: python -m pytest).
- boundaries.md (기본 글로브 패턴이 있는 영역 템플릿: 포맷팅은 Yellow 영역, 데이터는 Red 영역).
- weak_spots.md (기준 위험 레지스트리 구조).
- architecture.md (기준 아키텍처 스캐폴드).
- tasks.md (활성 목표, 팀 체크리스트 및 위임 레지스트리).
패스 2: 저장소 심층 분석, 원칙 및 셸 스킬
-
필수 핵심 검사 체크리스트: 핵심 모듈의 소스 코드를 읽지 않고
weak_spots.md및architecture.md를 보일러플레이트 템플릿으로 채우는 것은 금지됩니다! 에이전트는 다음 중요 영역에 대해read_file호출을 실행해야 합니다:- 스토리지 및 데이터베이스: 기본 데이터 액세스 모듈 (
storage.py, 리포지토리, 모델)을 읽습니다. 모놀리식 크기(LOC 수), 스키마 결합도 및 마이그레이션 설정을 평가합니다. - 외부 API 및 서비스 클라이언트: 통합 모듈(AI 모델 SDK, 외부 클라이언트)을 읽습니다. 재시도, 타임아웃, 폴백 및 전역 싱글톤을 확인합니다.
- 컨테이너화 및 런타임:
Dockerfile,docker-compose.yml및 CI 워크플로우 (.github/workflows/)를 읽습니다. 시스템 바이너리 종속성 (FFmpeg, 유틸리티), 사용자 권한 (UID) 및 데이터 볼륨 마운트를 확인합니다. - 사용자 인터페이스 및 입력: 키보드/라우터 모듈을 읽습니다. 플랫폼 제약 조건 (예: Telegram
callback_data의 64바이트 제한, FSM 상태, 파괴적 작업 확인)을 확인합니다.
- 스토리지 및 데이터베이스: 기본 데이터 액세스 모듈 (
-
대화형 보정 인터뷰 (성문화된 2-질문 프로토콜): 자동화된 스캔은 코드에 무엇이 있는지 식별하지만, 기록되지 않은 역사적 맥락, 비즈니스 불변 조건 또는 프로덕션 민감성을 감지할 수 없습니다. 에이전트는 (
ask_question도구 또는 직접 대화형 프롬프트를 통해) 정확히 2개의 집중 질문을 하는 간결하고 체계적인 대화형 인터뷰를 수행합니다:- 질문 1 (North Stars 및 핵심 불변 조건): "어떤 주요 아키텍처 불변 조건, 비즈니스 규칙 및 프로덕션 제약 조건 (North Stars)을 어떤 수정에서도 위반해서는 안 됩니까?"
- 질문 2 (Red Zone 및 민감 경로): "어떤 특정 디렉토리 또는 모듈 (빌링, DB, 암호화, 키, 레거시)이 중요하며 Red Zone에 엄격히 배치되어야 합니까?"
답변 처리:
- 질문 1에 대한 사용자 답변은 즉시
AGENTS.md의 섹션 1 ("원칙 및 아키텍처 방향 (North Stars)")에 통합됩니다. - 질문 2에 대한 사용자 답변은 단일 패스 플러시 전에
boundaries.md의 Red Zone에 매핑됩니다. - 사용자가 건너뛰거나 빈 응답을 제공하는 경우, 핵심 검사 체크리스트에서 추론된 방향으로 정상적으로 폴백합니다.
-
프로젝트 개념 및 원칙 보정: 체크리스트 결과와 인터뷰 답변을 2-3개의 간결한 아키텍처 방향(North Stars)으로 종합하여 모순되는 에이전트 작업을 방지합니다.
-
에이전트 셸 레지스트리에서 스택 스킬 매칭: 저장소 스택을 에이전트 환경에서 사용 가능한 특수 스킬 (
~/.gemini/config/skills/및 내장)에 매핑합니다:- Python / uv / ruff →
python-pro - FastAPI →
fastapi-pro - TypeScript / JavaScript →
typescript-expert - Next.js →
nextjs-best-practices - Docker / Dockerfile / Compose →
docker-expert - PostgreSQL / SQL / migrations →
postgresql-optimization,sql-pro - Kubernetes / Helm →
kubernetes-architect - Telegram bot / aiogram →
telegram-bot-builder - CI/CD pipelines →
github-actions-creator - Clean code & review →
clean-code,code-reviewer
- Python / uv / ruff →
-
경계 보정 (
boundaries.md): 실제 프로젝트 디렉토리에 대한.agents/project_knowledge/boundaries.md의 글로브 패턴을 개선합니다:- Default Deny / 100% 경로 커버리지 (매핑되지 않은 디렉토리 없음): 무시되지 않은 모든 최상위 소스 디렉토리가 명시적으로 영역에 할당되도록 보장합니다. Default Deny (Black Zone) 규칙을 추가합니다: 매핑되지 않은 경로는 기본적으로 엄격한 Red Zone입니다.
- 테스트 영역 차별화:
- 새로운 기능에 대한 새 테스트 생성 — Green 영역.
- 기존 회귀 테스트 스위트 (
tests/**,*_test.*,*.spec.*) — 엄격한 Yellow 영역이며, 어설션(assert/expect) 약화를 금지하는 불변 조건이 있습니다. - 아키텍처 무결성, API 계약 및 데이터 스키마 테스트 (
*integrity*,*contract*,*schema*, E2E) — 엄격한 Red 영역.
- 포맷팅/이스케이핑 모듈 및 템플릿 엔진 — 엄격한 Yellow 영역.
- 데이터베이스 파일 및 디렉토리 (
data/**,*.db,*.sqlite*) — 엄격한 Red 영역. - 플레이스홀더 경로를 실제 마이그레이션 경로 (
alembic/versions/**,prisma/migrations/**등)로 바꿉니다. - 경로/컨트롤러 경로를 실제 서브시스템 위치로 바꿉니다.
-
위험 및 취약점 분석 (
weak_spots.md): 핵심 검사 중 식별된 구체적인 기술 부채(모놀리스, 싱글톤), 외부 런타임 종속성(Redis, Postgres, 메시지 브로커, FFmpeg와 같은 시스템 유틸리티), 플랫폼 제약 조건 및.env.example의 필수 변수를 기록합니다. -
아키텍처 슬라이스 채우기 (
architecture.md): 검사된 핵심 모듈을 기반으로 고수준 스택, 서브시스템, 백그라운드 작업/스케줄러 및 데이터 흐름을 설명합니다.- 조건부 종단간 데이터 흐름: 멀티 티어, 클라이언트-서버, API 또는 UI 구성 요소가 감지될 때마다 "종단간 데이터 흐름 (사전 비행 흐름 추적)" 스키마를 생성합니다 (
[Origin: UI/CLI/Event] ➔ [Transport: API Route / Message] ➔ [Domain / Storage: Persistence] ➔ [Assembly / Packager] ➔ [Consumer: Client / Daemon]매핑). 외부 통신 또는 지속성 계층 없이 순수 단일 계층 CLI 또는 stdlib 라이브러리의 경우, 컨텍스트 팽창을 방지하기 위해 이 섹션을 생략합니다.
- 조건부 종단간 데이터 흐름: 멀티 티어, 클라이언트-서버, API 또는 UI 구성 요소가 감지될 때마다 "종단간 데이터 흐름 (사전 비행 흐름 추적)" 스키마를 생성합니다 (
-
메모리 내 종합 플러시 프로토콜: 에이전트는 중간 초안을 디스크에 쓰지 않습니다. 모든 불변 조건은 패스 1과 2 동안 작업 메모리에서 종합된 후, 다음 엄격한 하향식 순서로 파일을 작성합니다:
- 단계 A: 사전 설치된 스킬 (
.agents/skills/record-observation/,sync-architecture/,ground-meta-project/) 및 자동화 스크립트 (scripts/check_boundaries.py,scripts/compact_memory.py(공유 저장소 설정인 경우)). - 단계 B: 지식 슬라이스 (
observations.md->boundaries.md->weak_spots.md->architecture.md). - 단계 C: 루트 패스포트 (
AGENTS.md) — 슬라이스 및 스택 스킬에 대한 참조를 집계하므로 엄격히 마지막.
- 단계 A: 사전 설치된 스킬 (
최종화 및 검증
Get-ChildItem -Recurse .agents또는ls -R .agents를 사용하여 생성/업데이트된 파일을 확인합니다.- 로컬 보이지 않는 오버레이 옵션:
외부/클라이언트 프로젝트에서 초기화하거나 Git 커밋 없이 개인 모드가 요청된 경우:
- 대상 저장소의
.git/info/exclude에AGENTS.md및.agents/를 추가합니다. git status를 확인합니다. 메타 프로젝트 파일이 추적되지 않은 파일에 나타나서는 안 됩니다.
- 대상 저장소의
- 사용자에게 간결한 요약을 출력합니다:
- 실행 모드 (초기 설정 vs 감사 및 업그레이드, 공유 vs 보이지 않는 오버레이).
- 생성/업데이트된 파일 트리.
- 캡처된 프로젝트 방향 (North Stars).
- 연결된 스택 스킬 목록.
포함된 참조 템플릿
템플릿: record-observation/SKILL.md
---
name: record-observation
description: >-
이 스킬을 사용하여 문서화되지 않은 버그, 환경 특이점, 런타임 에지 케이스
또는 명확하지 않은 솔루션을 저장소의 `.agents/project_knowledge/observations.md` 테이블에 기록합니다.
---
# 저장소 지식 베이스에 관찰 기록
1. `.agents/project_knowledge/observations.md`가 존재하는지 확인합니다.
2. 마지막 20개 행에서 중복을 확인합니다.
3. 항목을 단일 Markdown 테이블 행으로 엄격히 추가합니다:
`| YYYY-MM-DD | [<category>] | <Path_or_component> | <Brief issue summary/fact> | <Solution or workaround> |`
카테고리: `[build]`, `[runtime]`, `[deps]`, `[db]`, `[api]`, `[test]`, `[env]`, `[ci]`, `[boundaries]`, `[orchestration]`, `[decommission]`, `[incident]`, `[init]` 또는 명시적 도메인 태그 (예: `[theme]`).
4. 행 수가 30-40개를 초과하면 해결된 레코드를 `.agents/project_knowledge/archive/observations-YYYY.md`로 아카이브합니다.
템플릿: sync-architecture/SKILL.md
---
name: sync-architecture
description: >-
이 스킬을 사용하여 저장소 모듈, 종속성 및 진입점을 분석하고
`.agents/project_knowledge/architecture.md`를 생성하거나 업데이트합니다.
---
# 프로젝트 아키텍처 슬라이스 동기화
1. 종속성 및 빌드 매니페스트를 읽습니다.
2. 진입점 및 최상위 디렉토리를 식별합니다.
3. 3-5개의 서브시스템, 그 역할 및 데이터 흐름을 식별합니다.
4. `.agents/project_knowledge/architecture.md`를 업데이트합니다.
5. 사용자에게 변경 사항에 대한 간략한 요약을 표시합니다.
템플릿: ground-meta-project/SKILL.md
---
name: ground-meta-project
description: >-
비상 접지 및 재조정 스킬: 실행 편집을 중단하고, 확대하여 AGENTS.md,
활성 역할 패스포트, boundaries.md 및 아키텍처 맵을 다시 읽고, 컨텍스트 드리프트를 진단하고, 나이를 재설정합니다.
템플릿: scripts/check_boundaries.py
#!/usr/bin/env python3
"""
경계 게이트 CLI - 파일 경로가 `.agents/project_knowledge/boundaries.md`에 정의된 영역을 준수하는지 확인합니다.
분석 및 포맷팅 스크립트에 대한 CI/사전 커밋 후크로 사용됩니다.
"""
템플릿: scripts/compact_memory.py
#!/usr/bin/env python3
"""
컨텍스트 로트 실드 및 메모리 컴팩터 - 에이전트 작업 메모리와 `.agents/project_knowledge/` 슬라이스 간의 저장소 지식을 동기화합니다.
`observations.md`가 사전 정의된 임계값을 초과할 때 또는 명시적 호출 시 자동화된 CI/CD 트리거를 통해 실행됩니다.
"""
핵심 원칙: 메타 프로젝트는 살아있는 문서입니다. 축적된 관찰을 보존하고, 비어 있거나 오래된 슬라이스를 채우며, 위험과 North Stars를 최신 상태로 유지함으로써 지속적인 리프레시를 수용합니다.
데이터 보존 명령:
observations.md의 모든 기존 행은 불가침입니다. 안전한 업그레이드 모드는 열을 추가하거나 구조화되지 않은 데이터를 명확히 할 수 있지만, 관찰 내용을 삭제하거나 잘라내는 것은 절대 안 됩니다.