AGENTS.md — code-forge Agent Instructions

이 파일은 AAIF(Agent Architecture Instruction Format) 표준에 따라 작성되었다. AI 에이전트(Codex/Cursor 포함)가 이 저장소에서 작업할 때 준수해야 할 규칙을 정의한다.

카탈로그(에이전트/스킬/훅/규칙 표)는 여기 없다 — 단일 소스 docs/REFERENCE.md 참조. 이 파일은 멀티모델 진입점 델타(수정 규칙 + 금지 작업)만 유지한다 (2026-06-12 H1 dedup).

프로젝트 구조 개요

code-forge/
├── agents/          # 플러그인 에이전트 .md (직접 편집 가능)
├── docs/            # 설계 원칙, 가이드, REFERENCE.md(카탈로그 단일 소스)
├── hooks/           # Claude Code 훅 스크립트
├── instructions/    # 멀티에이전트 협업 가이드
├── modules/         # 스택별 컨벤션 모듈
├── plugins/smith/   # Smith 빌드 시스템 (프로젝트 에이전트 소스)
├── presets/         # 스택 프리셋
├── rules/           # 사고 모델 + 코딩 표준
├── skills/          # 스킬 커맨드 (/start, /handoff 등 — 목록은 REFERENCE.md)
├── CLAUDE.md        # 플러그인 메인 설명서 (포인터 중심)
└── AGENTS.md        # 이 파일

설계 원칙

이 플러그인을 수정/확장할 때 docs/design-principles.md를 반드시 참조한다. 모든 변경은 설계 원칙에 위배되지 않아야 한다.

에이전트 수정 규칙

플러그인 에이전트 (agents/)

agents/ 파일은 직접 편집한다. Smith 빌드 불필요.

프로젝트 전용 에이전트

1. /code-forge:smith-create-agent → .agents/agents/ 에 생성 (STATE+ACT 조합, setup에서 자동 호출됨)
2. /code-forge:smith-build --project → .claude/agents/ 컴파일

Smith 빌드는 프로젝트 에이전트 전용. STATE/ACT 부품은 plugins/smith/agents/state/, plugins/smith/agents/act/.

릴리스 절차 (버전 범프 시 필수)

1. CHANGELOG.md 최상단에 새 버전 섹션 작성 — 추가/변경/수정/제거, 사용자 관점 패치노트
2. .claude-plugin/plugin.json version 범프 — CHANGELOG 갱신과 같은 커밋에
3. git push origin main → claude plugin update code-forge@forge-market --scope project (+ --scope local)
4. 캐시(~/.claude/plugins/cache/forge-market/code-forge/<ver>/)에서 핵심 변경 1개 spot-check — "소스 수정 ≠ 배포" (2026-06-11 교훈: 픽스가 소스에만 있고 캐시는 한 달 stale이었음)

금지 작업

카탈로그 참조 (단일 소스)