toki/iop
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
iop/agent-ops/skills/common/init-agent-ops/SKILL.md

14 KiB
Raw Blame History

name version description
init-agent-ops 1.1.9 프로젝트 상태를 판별하고 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 archive hard read/glob deny를 제거하고, 필요 시 명시 경로로 읽을 수 있게 둔다. opencode.json은 watcher ignore에 agent-task/archive/**, agent-roadmap/archive/**를 둘 수 있다

에이전트별 파일명:

실제 생성/동기화 대상 목록은 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와 내용이 중복되지 않도록 한다.

도메인 매핑 테이블 형식

## 도메인 매핑

| 경로 패턴 | 도메인 | 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` |

프로젝트 스킬 라우팅 형식

## 스킬 라우팅

| 요청 키워드 | 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 분석을 보완한다.

./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이 없으면 archive hard read/glob deny 없이 생성하고, 있으면 가능한 경우 기존 설정을 보존하며 archive hard read/glob deny를 제거한다
    • archive는 일반 작업에서 읽지 않도록 AI ignore, watcher ignore, 공통 규칙으로 제한하되, .claude/settings.json이나 opencode.json의 hard read/glob deny에는 두지 않는다
    • 기존 .claude/settings.json이나 opencode.json에 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/** 또는 agent-roadmap/archive/** hard read/glob deny가 남아 있지 않은가
  • 기존 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와 중복되는 내용을 넣지 않는다.