appsok/agent-ops/skills/common/init-agent-ops/SKILL.md

---
name: init-agent-ops
version: 1.1.9
description: 프로젝트 상태를 판별하고 agent-ops 기본 스캐폴드를 생성하기 위한 초기 규칙
---

# init-agent-ops

## 목적

프로젝트에 Agent-Ops 구조가 없거나 불완전할 때,
현재 프로젝트 상태를 분석하여 다음을 세팅한다.

1. 에이전트 진입 파일
2. AI ignore / permission 기본 설정
3. agent-ops 기본 폴더 구조
4. rules/project/rules.md (프로젝트 특화 규칙, 분석 후 생성)
5. 초기 domain rule 초안
6. 초기 local 테스트 환경
7. 초기 skill (필요 시)

"현재 프로젝트에 맞는 최소 스캐폴드" 생성을 우선한다.

## 언제 호출할지

- 프로젝트에 agent-ops 구조가 없을 때
- agent-ops 구조가 불완전하여 재설정이 필요할 때
- 사용자가 "agent-ops 초기화해줘", "에이전트 설정해줘" 요청 시

## 입력

- `project-type`: 신규 / 운영중 (선택, 미지정 시 자동 판별)

## 먼저 확인할 것

- [ ] 프로젝트 루트에 기존 agent-ops 관련 파일(`CLAUDE.md`, `agent-ops/` 등)이 있는지 확인
- [ ] `.agent-ops-source` 파일이 있는지 확인 (공통 관리 레포 여부)
- [ ] 기존 진입 파일(`CLAUDE.md`, `GEMINI.md` 등)이 있는지 확인
- [ ] 기존 AI ignore / permission 파일(`.geminiignore`, `.aiexclude`, `.claude/settings.json`, `opencode.json` 등)이 있는지 확인
- [ ] `agent-ops/skills/common/create-test/SKILL.md`가 있는지 확인

## 핵심 원칙

- 기존 구조를 우선한다.
- 새 파일 생성은 꼭 필요한 최소 범위로 제한한다.
- 도메인은 발명하지 말고 현재 구조에서 발견한다.
- 처음에는 핵심 도메인만 생성한다.
- 반복되는 작업만 초기 skill로 만든다.
- 불확실한 내용은 후보로 제시한다.

## 상태 판별

### 신규 프로젝트
- 코드/폴더 구조가 단순하다
- 도메인 경계가 아직 약하다
- Agent-Ops 관련 파일이 없다

### 운영중 프로젝트
- 모듈/폴더/패키지 경계가 보인다
- 반복 작업이 드러난다
- 핵심 책임 경계가 식별된다

## 생성 대상

| 파일 | 방법 |
|------|------|
| `GEMINI.md`, `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.clinerules` 등 진입 파일 | `rules/common/rules.md`를 `agent-ops/bin/entry-files.sh`의 파일 목록으로 프로젝트 루트에 복사 |
| `agent-ops/.version` | 공통 관리 레포의 VERSION 파일을 그대로 복사 (프레임워크 버전 추적용) |
| `agent-ops/bin/` | 공통 스크립트 전체 복사 (진입 파일 목록의 단일 기준인 `entry-files.sh` 포함) |
| `agent-ops/rules/common/` | 공통 폴더 전체 복사 (수정 금지) |
| `agent-ops/skills/common/` | 공통 폴더 전체 복사 (수정 금지) |
| `agent-ops/rules/project/rules.md` | 프로젝트 분석 후 생성 |
| `agent-ops/rules/project/domain/<domain>/rules.md` | 도메인 분석 후 생성 |
| `agent-ops/rules/private/` | 폴더만 생성 (내용은 개인이 작성) |
| `.gitignore`에 `agent-ops/rules/private/` 추가 | git 추적 제외 |
| `.gitignore`의 Agent-Ops 관리 block | `*.log` 같은 전역 ignore가 있어도 `agent-task/**/*.md`, `agent-task/**/*.log` task 산출물이 추적되도록 unignore하고 `agent-roadmap/current.md`는 로컬 포인터로 ignore |
| `agent-test/local/rules.md` | `init-agent-ops.sh`가 최소 내용으로 생성 |
| `agent-test/local/project-smoke.md` | 도메인이 아직 없으면 `init-agent-ops.sh`가 fallback baseline으로 생성 |
| `agent-test/local/<domain>-smoke.md` | domain rule 생성 후 각 도메인별 기본 smoke 테스트 뼈대로 생성 |
| `.gitignore`에 `agent-test/local/`, `agent-test/runs/` 추가 | `init-agent-ops.sh`가 local 테스트 환경/로그를 git 추적 제외 |
| `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore` | 사용자 항목은 보존하고 Agent-Ops 관리 block에 `agent-task/archive/**`, `agent-roadmap/archive/**` 추가 |
| `.claude/settings.json`, `opencode.json` | `agent-task/archive/**` 읽기/검색 제외 설정을 생성 또는 병합한다. `agent-roadmap/archive/**`는 필요 시 링크로 읽을 수 있어야 하므로 hard read/glob deny에서 제거한다 |

에이전트별 파일명:

실제 생성/동기화 대상 목록은 `agent-ops/bin/entry-files.sh`의 `AGENT_OPS_ENTRY_FILES`를 단일 기준으로 사용한다.

| 에이전트 | 파일명 |
|---------|--------|
| Gemini | `GEMINI.md` |
| Claude | `CLAUDE.md` |
| Kilo Code / OpenCode | `AGENTS.md` |
| Cursor | `.cursorrules` |
| Cline | `.clinerules` |

## 에이전트 진입 파일 원칙

진입 파일은 `rules/common/rules.md` 내용 그대로를 에이전트별 파일명으로 복사한다.
별도 내용을 추가하거나 수정하지 않는다.

## Rule 구조 원칙

### rules/common/rules.md
- 공통 관리 레포에서 제공. 프로젝트에서 직접 수정하지 않는다. 
- 실제 사용은 진입점 파일들에서 사용된다.

포함 항목:
- 기본 원칙
- 공통 스킬 라우팅 (router.md 참조)
- project/rules.md 로드 지시

### rules/project/rules.md
init-agent-ops가 프로젝트를 분석하여 생성한다.

포함 항목:
- 응답 언어
- 프로젝트 개요 / 주요 구조
- 기술 스택
- 프로젝트 특화 컨벤션
- 도메인 매핑 테이블 (경로 패턴 → domain rules.md)
- 프로젝트 스킬 라우팅 (해당 시)

common/rules.md와 내용이 중복되지 않도록 한다.

#### 도메인 매핑 테이블 형식

```markdown
## 도메인 매핑

| 경로 패턴 | 도메인 | rules.md |
|----------|--------|----------|
| `src/order/**` | order | `agent-ops/rules/project/domain/order/rules.md` |
| `src/payment/**` | payment | `agent-ops/rules/project/domain/payment/rules.md` |
| `src/common/**` | common | `agent-ops/rules/project/domain/common/rules.md` |
```

#### 프로젝트 스킬 라우팅 형식

```markdown
## 스킬 라우팅

| 요청 키워드 | SKILL.md |
|------------|----------|
| 테스트 실행해줘 | `agent-ops/skills/project/run-test/SKILL.md` |
```

### domain rule
각 도메인 rules.md에는 아래만 둔다.

- frontmatter metadata
  - `domain`
  - `last_rule_review_commit`: 생성 직전 `git rev-parse HEAD`
  - `last_rule_updated_at`: 생성일 `YYYY-MM-DD`
- 목적 / 책임
- 포함 경로
- 제외 경로
- 주요 구성 요소
- 유지할 패턴
- 다른 도메인과의 경계
- 금지 사항

## DDD 기준

- **Core Domain**: 핵심 가치와 주요 유즈케이스
- **Supporting Domain**: 핵심 도메인을 지원
- **Generic / Common**: 여러 도메인이 공통으로 사용

도메인은 실제 폴더, 모듈, 패키지, 책임 경계와 연결되어야 한다.

## 실행 (Execution)

지정한 대상 디렉토리에 agent-ops 기본 스캐폴드와 local 테스트 환경을 생성한다.
스크립트 실행 후 이 skill의 실행 절차에 따라 project/domain 분석을 보완한다.

```bash
./agent-ops/bin/init-agent-ops.sh <target_directory>
```

## 실행 절차

1. **상태 판별**
   - 프로젝트 구조, 모듈 경계, agent-ops 파일 유무를 분석하여 신규/운영중을 판별한다

2. **에이전트 진입 파일 생성**
   - `rules/common/rules.md`를 `agent-ops/bin/entry-files.sh`의 파일 목록으로 프로젝트 루트에 복사한다

3. **AI ignore / permission 기본 설정**
   - `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에는 사용자 항목을 건드리지 않고 Agent-Ops 관리 block만 추가하거나 교체한다
   - Agent-Ops 관리 block에는 `agent-task/archive/**`와 `agent-roadmap/archive/**`를 넣는다
   - `.claude/settings.json`, `opencode.json`이 없으면 `agent-task/archive/**` 읽기/검색 제외 설정을 생성하고, 있으면 가능한 경우 기존 설정을 보존하며 필요한 제외 설정만 병합한다
   - `agent-roadmap/archive/**`는 일반 작업에서 읽지 않도록 AI ignore와 로드맵 규칙으로 제한하되, `.claude/settings.json`이나 `opencode.json`의 hard read/glob deny에는 두지 않는다
   - 기존 `.claude/settings.json`이나 `opencode.json`에 `agent-roadmap/archive/**` hard read/glob deny가 있으면 init-agent-ops 표준에 맞게 제거한다
   - 대상 루트에 `.agent-ops-source`가 있으면 AI ignore / permission 파일은 보강하지 않는다
   - `agent-task/archive/**`와 `agent-roadmap/archive/**` ignore 항목은 `.gitignore`에 추가하지 않는다
   - `.gitignore`에는 Agent-Ops 관리 block으로 `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`, `agent-roadmap/current.md`만 추가하거나 갱신한다

4. **agent-ops 폴더 구조 복사**
   - 공통 관리 레포의 `agent-ops/` 공통 폴더(bin, rules/common, skills/common)를 복사한다
   - `agent-ops/.version` 파일을 복사한다

5. **rules/project/rules.md 생성**
   - 프로젝트를 분석하여 응답 언어, 프로젝트 개요, 기술 스택 등을 채운다
   - common/rules.md와 내용이 중복되지 않도록 한다

6. **도메인 분석 및 domain rule 생성**
   - 신규 프로젝트: 핵심 domain placeholder 2~4개만 제안한다. domain rules를 과도하게 채우지 않는다
   - 운영중 프로젝트: Core/Supporting/Generic 도메인을 식별하고 실제 경로를 반영한 초안을 생성한다

7. **초기 local 테스트 환경 생성**
   - `init-agent-ops.sh`가 `agent-test/local/rules.md`를 최소 내용으로 자동 생성한다
   - `init-agent-ops.sh`는 기존 domain rule이 있으면 각 도메인별 `agent-test/local/<domain>-smoke.md`를 생성하고 라우팅한다
   - 기존 domain rule이 없으면 `agent-test/local/project-smoke.md` fallback 뼈대를 생성하고 라우팅한다
   - `init-agent-ops.sh`가 `.gitignore`에 `agent-test/local/`과 `agent-test/runs/`를 자동 추가한다
   - 스크립트 실행 후 누락되었으면 대상 프로젝트의 `agent-ops/skills/common/create-test/SKILL.md`를 읽고 `env=local`, `test-profile` 없음으로 보완한다
   - domain rule을 새로 생성한 경우, 각 생성 도메인마다 `agent-test/local/<domain>-smoke.md` 기본 뼈대를 만들고 `agent-test/local/rules.md`에 라우팅을 추가한다
   - 도메인별 테스트 문서는 상세 명령을 모르면 `<확인 필요>`를 남기더라도 생략하지 않는다

8. **초기 skill 제안**
   - 신규 프로젝트: 최소 2개만 제안한다
   - 운영중 프로젝트: 반복 작업 기반으로 필요한 skill을 제안한다

9. **결과 보고**
   - 상태 판별 결과, 생성된 파일 목록, 도메인 제안, skill 제안, 주의사항을 출력한다

## 출력 형식

### 상태 판별
- Agent-Ops 상태: 없음 / 부분 적용 / 운영중
- 프로젝트 상태: 신규 / 운영중
- 근거: 짧게 요약

### 스캐폴드 계획
- 생성할 파일
- 바로 채울 파일
- placeholder로 둘 파일

### 도메인 제안
- Core Domain
- Supporting Domain
- Generic / Common

### 초기 skill 제안
- skill 이름
- 필요한 이유

### 주의사항
- 지금 만들지 말아야 할 것
- 아직 확정하면 안 되는 것

## 실행 결과 검증

- [ ] `agent-ops/bin/entry-files.sh`의 모든 진입 파일이 프로젝트 루트에 존재하고, 내용이 초기화에 사용한 `rules/common/rules.md`와 일치하는가
- [ ] `agent-ops/rules/common/rules.md`가 대상 프로젝트에 남아 있고 초기화에 사용한 `rules/common/rules.md`와 일치하는가
- [ ] `agent-ops/rules/project/rules.md`가 생성되었고, 필수 항목(응답 언어, 프로젝트 개요, 기술 스택)이 포함되어 있는가
- [ ] 생성된 domain rules.md가 `domain-rule-template.md` 형식을 따르는가
- [ ] `rules/project/rules.md`의 도메인 매핑 테이블에 생성된 도메인이 모두 등록되어 있는가
- [ ] `.gitignore`에 `agent-ops/rules/private/` 항목이 추가되어 있는가
- [ ] `.gitignore`에 Agent-Ops 관리 block이 있고 `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`, `agent-roadmap/current.md`가 포함되어 있는가
- [ ] `agent-test/local/rules.md`가 생성되었는가
- [ ] 생성되었거나 기존에 있던 모든 domain rule에 대응하는 `agent-test/local/<domain>-smoke.md`가 있는가
- [ ] domain rule이 아직 없으면 `agent-test/local/project-smoke.md` fallback이 있는가
- [ ] `agent-test/local/rules.md`에 생성된 테스트 profile 라우팅이 연결되었는가
- [ ] `.gitignore`에 `agent-test/local/`과 `agent-test/runs/`가 추가되어 있는가
- [ ] `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에 Agent-Ops 관리 block이 있고 그 안에 `agent-task/archive/**`와 `agent-roadmap/archive/**`가 포함되어 있는가
- [ ] `.claude/settings.json`, `opencode.json`에 `agent-task/archive/**` 제외 설정이 있거나, 병합 불가 시 수동 병합 안내를 출력했는가
- [ ] `.claude/settings.json`, `opencode.json`에 `agent-roadmap/archive/**` hard read/glob deny가 남아 있지 않은가
- [ ] 기존 `agent-roadmap/archive/**` hard deny가 있으면 init-agent-ops 표준에 맞게 제거했는가
- [ ] `.gitignore`에 `agent-task/archive/**` 또는 `agent-roadmap/archive/**` ignore 항목을 추가하지 않았는가
- 검증 실패 시: 누락된 파일/항목을 사용자에게 알리고 해당 부분만 보완한다

## 금지 사항

- 진입 파일에 rules/common/rules.md 외 내용을 추가하지 않는다.
- `agent-task/archive/**`와 `agent-roadmap/archive/**` ignore 항목을 `.gitignore`에 추가하지 않는다.
- `.gitignore`의 Agent-Ops 관리 task 산출물 unignore 예외를 제거하지 않는다.
- local 테스트 환경 파일을 git 추적 대상으로 만들지 않는다.
- domain rule이 확인된 경우 도메인별 기본 smoke 테스트 문서를 생략하지 않는다.
- 실제 구조보다 앞선 추상 구조를 강요하지 않는다.
- 처음부터 많은 domain / skill을 만들지 않는다.
- rules/common/rules.md를 프로젝트에서 직접 수정하지 않는다.
- rules/project/rules.md에 rules/common/rules.md와 중복되는 내용을 넣지 않는다.