diff --git a/agent-ops/.version b/agent-ops/.version new file mode 100644 index 0000000..9084fa2 --- /dev/null +++ b/agent-ops/.version @@ -0,0 +1 @@ +1.1.0 diff --git a/agent-ops/GUIDE.md b/agent-ops/GUIDE.md new file mode 100644 index 0000000..17afb98 --- /dev/null +++ b/agent-ops/GUIDE.md @@ -0,0 +1,168 @@ +# Agent Context Framework 적용 가이드 + +이 문서는 `agent-ops/` 폴더를 프로젝트에 복사한 뒤 참고하는 가이드입니다. + +--- + +## 간단 적용 + +**1. `agent-ops/` 폴더를 타겟 프로젝트 루트에 복사합니다.** + +**2. 에이전트에게 아래와 같이 정확한 경로를 지정해 초기화를 요청합니다.** + +> 초기 세팅 전에는 진입 파일(CLAUDE.md 등)이 없어 라우팅이 불가능하므로, 반드시 스킬 파일 경로를 직접 안내해야 합니다. + +``` +agent-ops/skills/common/init-agent-ops/SKILL.md 를 읽고 실행해줘. +``` + +`init-agent-ops` 스킬이 프로젝트를 분석하고 다음을 자동 생성합니다. +- 진입 파일 (CLAUDE.md 등) +- `rules/project/rules.md` +- `rules/project/domain//rules.md` + +--- + +## 구성 + +``` +agent-ops/ +├── GUIDE.md # 이 파일 (적용 가이드) +├── .version # 프레임워크 버전 (타겟 프로젝트 버전 추적용) +├── rules/ +│ ├── common/ # 공통 규칙 (수정 금지) +│ │ ├── rules.md # 공통 규칙 (에이전트 진입 파일로 사용) +│ │ └── _templates/ +│ │ └── domain-rule-template.md +│ ├── project/ # 프로젝트 규칙 (수정 가능) +│ │ ├── rules.md # 프로젝트 특화 규칙 (init-agent-ops가 생성) +│ │ └── domain/ # 도메인별 규칙 +│ │ └── /rules.md +│ └── private/ # 개인 규칙 (git 제외, 선택) +│ └── rules.md +└── skills/ + ├── common/ # 공통 스킬 (수정 금지) + │ ├── router.md # 공통 스킬 라우터 + │ ├── _templates/ + │ │ └── skill-template.md + │ ├── init-agent-ops/SKILL.md # scaffold 초기화 + │ ├── sync-agent-ops/SKILL.md # 진입 파일 재적용 + │ ├── commit-push/SKILL.md # 커밋 & 푸시 + │ ├── create-domain-rule/SKILL.md # 도메인 규칙 생성 + │ ├── create-skill/SKILL.md # 스킬 생성 + │ └── version-bump/SKILL.md # 버전 업데이트 + └── project/ # 프로젝트 스킬 (수정 가능) + └── /SKILL.md +``` + +--- + +## 적용 방법 + +### 1. 복사 + +이 레포의 `agent-ops/` 폴더를 타겟 프로젝트 루트에 복사합니다. + +``` +project-root/ +├── agent-ops/ ← 복사 +└── ... +``` + +### 2. 진입 파일 배치 + +`agent-ops/rules/common/rules.md`를 사용하는 에이전트에 맞는 파일명으로 프로젝트 루트에 복사합니다. + +| 에이전트 | 파일명 | +|---------|--------| +| Claude | `CLAUDE.md` | +| Gemini | `GEMINI.md` | +| Kilo Code / OpenCode | `AGENTS.md` | +| Cursor | `.cursorrules` | +| Cline | `.clinerules` | + +``` +project-root/ +├── CLAUDE.md ← rules/common/rules.md 복사 +├── agent-ops/ +└── ... +``` + +### 3. scaffold 스킬 실행 + +AI 에이전트에게 초기화를 요청합니다. + +``` +agent-ops 초기화해줘. +``` + +에이전트가 프로젝트 구조를 분석하고 다음을 자동 생성합니다: +- `rules/project/rules.md` — 프로젝트 특화 규칙 (응답 언어, 프로젝트 개요, 기술 스택) +- `rules/project/domain//rules.md` — 도메인별 규칙 초안 + +### 4. 개인 규칙 설정 (선택) + +`agent-ops/rules/private/rules.md`를 생성하여 개인 선호 규칙을 정의할 수 있습니다. + +- 응답 언어, 출력 스타일 등 개인 설정 +- 팀 공통 규칙(`project/rules.md`)과 충돌하지 않는 범위에서 자유롭게 작성 +- `.gitignore`에 `agent-ops/rules/private/`가 추가되어 있으므로 커밋되지 않습니다 + +### 6. 내용 확인 및 보완 + +스킬 실행 후 다음 항목을 확인합니다. + +| 파일 | 확인할 내용 | +|------|------------| +| `rules/project/rules.md` | 응답 언어, 프로젝트 개요, 기술 스택, 특화 컨벤션, 도메인 매핑 테이블 | +| `rules/project/domain/*/rules.md` | 도메인별 경로, 구성 요소, 패턴, 경계 | + +### 7. 개발 시작 + +구성이 완료되면 에이전트는 모든 작업 요청 시 자동으로 rules와 skills를 참조합니다. + +--- + +## 파일 흐름 + +``` +진입 파일 (CLAUDE.md 등) = rules/common/rules.md 내용 + → skills/common/router.md (공통 스킬 요청 시) + → skills/common//SKILL.md + → rules/project/rules.md + → skills/project//SKILL.md 또는 rules/project/domain//rules.md +``` + +--- + +## 공통 파일 수정 보호 + +에이전트는 프로젝트 루트의 `.agent-ops-source` 마커 파일 유무로 공통 파일 수정 가능 여부를 판단합니다. + +| 마커 | 의미 | 공통 파일 수정 | +|------|------|--------------| +| `.agent-ops-source` 있음 | 공통 관리 레포 | 허용 | +| `.agent-ops-source` 없음 | 타겟 프로젝트 | **금지** | + +**중요**: `agent-ops/` 폴더를 타겟 프로젝트에 복사할 때 `.agent-ops-source` 파일은 복사하지 마세요. 이 파일은 `agent-ops/` 밖(프로젝트 루트)에 있으므로 `agent-ops/` 폴더만 복사하면 자연스럽게 제외됩니다. + +수정이 필요한 경우 공통 관리 레포에 반영하고, 해당 변경 내용을 각 프로젝트에 수동으로 싱크합니다. + +각 공통 파일의 frontmatter에는 개별 `version`이 명시되어 있습니다. + +프레임워크 전체 버전은 `agent-ops/.version` 파일에 기록됩니다. `init-agent-ops` 실행 시 이 파일이 타겟 프로젝트에 함께 복사되므로, 타겟 프로젝트의 `agent-ops/.version`을 확인하면 어느 시점의 프레임워크를 기반으로 하는지 파악할 수 있습니다. + +--- + +## 수정 가능 / 불가능 파일 구분 + +| 구분 | 파일 | 수정 | +|------|------|------| +| 공통 (수정 금지) | `.version` | 공통 레포에서만 수정 | +| 공통 (수정 금지) | `rules/common/rules.md` | 공통 레포에서만 수정 | +| 공통 (수정 금지) | `rules/common/_templates/*.md` | 공통 레포에서만 수정 | +| 공통 (수정 금지) | `skills/common/*/SKILL.md` (공통 스킬) | 공통 레포에서만 수정 | +| 공통 (수정 금지) | `skills/common/_templates/*.md` | 공통 레포에서만 수정 | +| 프로젝트 (수정 가능) | `rules/project/rules.md` | 프로젝트에 맞게 수정 | +| 프로젝트 (수정 가능) | `rules/project/domain/*/rules.md` | 프로젝트에 맞게 수정 | +| 프로젝트 (수정 가능) | `skills/project/*/SKILL.md` (프로젝트 스킬) | 자유롭게 수정 | diff --git a/agent-ops/rules/common/_templates/domain-rule-template.md b/agent-ops/rules/common/_templates/domain-rule-template.md new file mode 100644 index 0000000..529e10d --- /dev/null +++ b/agent-ops/rules/common/_templates/domain-rule-template.md @@ -0,0 +1,29 @@ +# + +## 목적 / 책임 + +<이 도메인이 담당하는 책임을 1~2문장으로> + +## 포함 경로 + +- `/` — <이 경로가 이 도메인에 속하는 이유> + +## 제외 경로 + +- `/` — <왜 이 도메인이 아닌지> + +## 주요 구성 요소 + +- `` — <역할> + +## 유지할 패턴 + +- <네이밍 규칙 또는 아키텍처 패턴> + +## 다른 도메인과의 경계 + +- **<인접 domain>**: <어디까지가 이 도메인이고 어디서부터 저 도메인인지> + +## 금지 사항 + +- <이 도메인 코드에서 하면 안 되는 것> diff --git a/agent-ops/rules/common/rules.md b/agent-ops/rules/common/rules.md new file mode 100644 index 0000000..29ccc4b --- /dev/null +++ b/agent-ops/rules/common/rules.md @@ -0,0 +1,17 @@ +# 공통 규칙 + +- 기존 구조를 우선한다. 새 파일 생성보다 기존 파일 수정을 우선한다. +- 코드 변경 전 관련 domain rule을 먼저 확인한다. +- 요청 범위를 넘는 변경을 하지 않는다. +- 불확실하면 단정하지 말고 후보를 제시한다. + +아래 요청은 `agent-ops/skills/common/router.md`를 읽고 수행한다. +- agent-ops 초기화 +- domain rule 생성 +- skill 생성 +- git commit / git push +- 버전 올려줘 +- agent-ops 업데이트 / 진입 파일 재적용 + +`agent-ops/rules/project/rules.md`와 +`agent-ops/rules/private/rules.md`를 읽고 작업을 시작한다. 파일이 없을경우 무시한다. diff --git a/agent-ops/rules/project/.gitkeep b/agent-ops/rules/project/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/agent-ops/skills/common/_templates/skill-template.md b/agent-ops/skills/common/_templates/skill-template.md new file mode 100644 index 0000000..2372acb --- /dev/null +++ b/agent-ops/skills/common/_templates/skill-template.md @@ -0,0 +1,57 @@ +--- +name: +version: 1.0.0 +description: <이 skill이 하는 일을 한 줄로 설명. 트리거 키워드 포함 권장> +depends: [] # 선택 — 의존 skill이 없으면 이 줄 삭제 +--- + +# + +## 목적 + +<이 skill이 해결하는 문제를 1~2문장으로 설명> + +## 언제 호출할지 + +- <이 skill을 호출해야 하는 상황 1> +- <이 skill을 호출해야 하는 상황 2> +- <이 skill을 호출해야 하는 상황 3> + +## 입력 + +- ``: <설명> (필수) +- ``: <설명> (선택) + +## 먼저 확인할 것 + +- [ ] <실행 전 반드시 확인해야 할 조건 1> +- [ ] <실행 전 반드시 확인해야 할 조건 2> + +## 실행 절차 + +1. **<단계명>** + - <세부 행동> + - <세부 행동> + +2. **<단계명>** + - <세부 행동> + +3. **결과 보고** + - <출력할 내용> + +## 실행 결과 검증 + +- [ ] <실행 후 확인해야 할 성공 조건 1> +- [ ] <실행 후 확인해야 할 성공 조건 2> +- 검증 실패 시: <실패 시 취할 행동 — 롤백, 사용자 알림, 재시도 등> + +## 출력 형식 + +``` +<출력 예시> +``` + +## 금지 사항 + +- <절대 하면 안 되는 것> +- <절대 하면 안 되는 것> diff --git a/agent-ops/skills/common/commit-push/SKILL.md b/agent-ops/skills/common/commit-push/SKILL.md new file mode 100644 index 0000000..09e8ace --- /dev/null +++ b/agent-ops/skills/common/commit-push/SKILL.md @@ -0,0 +1,124 @@ +--- +name: commit-push +version: 1.0.0 +description: 변경 사항을 커밋하고 원격에 푸시한다. "커밋해줘", "푸시해줘", "커밋하고 푸시" 요청 시 사용한다. +--- + +# commit-push + +## 목적 + +현재 변경 내용을 분석하여 한국어 커밋 메시지를 작성하고, 커밋 및 푸시를 수행한다. + +## 언제 호출할지 + +- "커밋해줘", "커밋하고 푸시해줘" 요청 시 +- "변경 사항 올려줘", "푸시해줘" 요청 시 +- 코드 작업 완료 후 "반영해줘", "올려줘" 요청 시 + +## 입력 + +- `scope`: 커밋 범위 — all(전체) 또는 특정 파일/경로 (선택, 기본값: all) +- `push`: 푸시 여부 (선택, 기본값: true) + +## 먼저 확인할 것 + +- [ ] 커밋할 변경 사항이 존재하는가 (`git status`로 확인) +- [ ] 현재 브랜치가 올바른 브랜치인가 +- [ ] `.env`, 시크릿 파일 등 민감한 파일이 스테이징에 포함되어 있지 않은가 + +## 실행 절차 + +1. **변경 사항 파악** + - `git status`로 변경/추가/삭제된 파일 목록을 확인한다 + - `git diff`로 구체적인 변경 내용을 확인한다 + - 변경 사항이 없으면 사용자에게 알리고 종료한다 + +2. **민감 파일 검사** + - 스테이징 대상에 아래 패턴이 포함되면 해당 파일을 제외하고 사용자에게 경고한다 + - `.env`, `.env.*` + - `*secret*`, `*credential*`, `*password*` + - `*.pem`, `*.key`, `*.p12` + - `.gitignore`에 이미 등록된 파일은 무시한다 + +3. **커밋 메시지 작성** + - 변경 내용을 분석하여 한국어로 커밋 메시지를 작성한다 + - 아래 메시지 규칙을 따른다 + +4. **사용자 확인** + - 커밋 메시지와 대상 파일 목록을 보여주고 승인을 받는다 + - 사용자가 메시지 수정을 요청하면 반영한다 + +5. **커밋 실행** + - scope에 따라 파일을 스테이징한다 + - all: 변경된 전체 파일을 개별적으로 `git add` + - 특정 경로: 해당 파일만 `git add` + - 승인된 메시지로 `git commit`을 실행한다 + +6. **푸시 실행** + - push가 true인 경우에만 실행한다 + - 현재 브랜치를 원격에 푸시한다 + - 원격 브랜치가 없으면 `-u origin {branch}`로 설정한다 + - 충돌 발생 시 사용자에게 알리고 중단한다 + +7. **결과 보고** + - 커밋 해시, 메시지, 변경 파일 수, 푸시 결과를 출력한다 + +## 커밋 메시지 규칙 + +### 형식 + +``` +<타입>: <변경 요약> + +<본문> (선택) +``` + +### 타입 목록 + +| 타입 | 용도 | +|------|------| +| 기능 | 새로운 기능 추가 | +| 수정 | 버그 수정 | +| 개선 | 기존 기능 개선, 리팩토링 | +| 문서 | 문서 추가/수정 | +| 설정 | 빌드, CI/CD, 설정 파일 변경 | +| 테스트 | 테스트 추가/수정 | +| 정리 | 코드 정리, 불필요 코드 제거 | + +### 작성 원칙 + +- **한국어**로 작성한다 +- 요약은 50자 이내로 간결하게 작성한다 +- 요약은 "~한다" 형태의 서술형으로 끝낸다 (예: "로그인 검증 로직을 추가한다") +- 본문은 **무엇을** 변경했는지가 아니라 **왜** 변경했는지를 쓴다 +- 변경 파일이 3개 이하이면 본문을 생략할 수 있다 +- 여러 성격의 변경이 섞여 있으면 가장 핵심적인 변경을 기준으로 타입을 정한다 + +## 출력 형식 + +``` +## 커밋 완료 + +- 브랜치: {브랜치명} +- 커밋: {해시} — {커밋 메시지 요약} +- 변경 파일: {n}개 + - {파일 경로}: {변경 유형} +- 푸시: {성공/생략/실패} +``` + +## 실행 결과 검증 + +- [ ] `git log -1`로 방금 생성한 커밋이 존재하고, 메시지가 승인된 내용과 일치하는가 +- [ ] 커밋에 포함된 파일 목록이 의도한 scope와 일치하는가 (`git diff-tree --no-commit-id --name-only -r HEAD`) +- [ ] push가 true인 경우, `git status`에서 "Your branch is up to date" 또는 원격과 동기화 상태인가 +- 검증 실패 시: 실패 원인(커밋 누락, 푸시 실패 등)을 사용자에게 알리고 재시도 여부를 확인한다 + +## 금지 사항 + +- `git add -A` 또는 `git add .`을 사용하지 않는다 (민감 파일 혼입 방지) +- `git push --force`를 사용하지 않는다 +- 사용자 확인 없이 커밋하지 않는다 +- 영어로 커밋 메시지를 작성하지 않는다 +- 변경 내용과 무관한 커밋 메시지를 작성하지 않는다 +- `--no-verify` 옵션을 사용하지 않는다 diff --git a/agent-ops/skills/common/create-domain-rule/SKILL.md b/agent-ops/skills/common/create-domain-rule/SKILL.md new file mode 100644 index 0000000..5e553c1 --- /dev/null +++ b/agent-ops/skills/common/create-domain-rule/SKILL.md @@ -0,0 +1,104 @@ +--- +name: create-domain-rule +version: 1.0.0 +description: 새로운 도메인 rules.md 파일을 생성하기 위한 범용 스킬 +--- + +# Create Domain Rule + +## 목적 + +`agent-ops/rules/project/domain//rules.md` 파일을 올바른 형식으로 생성한다. +실제 프로젝트 폴더 구조를 분석하여 경로와 구성 요소를 자동으로 채운다. +생성 후 `rules/project/rules.md`의 도메인 매핑 테이블에 항목을 추가한다. + +## 언제 호출할지 + +- 새로운 도메인 영역의 코드를 처음 변경하기 전에 +- 기존 domain rule이 없는 경로에 대해 규칙이 필요할 때 +- 사용자가 특정 도메인의 rule 파일을 만들어 달라고 요청할 때 +- agent-ops 초기 scaffold 이후 도메인을 추가 확장할 때 + +## 입력 + +- `domain-name`: 생성할 도메인 이름, kebab-case (필수) +- `domain-type`: `core` / `supporting` / `generic` 중 하나 (필수) +- `path-hints`: 이 도메인에 해당하는 경로 힌트 목록 (선택, 없으면 자동 탐색) + +## 먼저 확인할 것 + +- [ ] `agent-ops/rules/project/domain//rules.md` 가 이미 존재하는지 확인 +- [ ] `agent-ops/rules/common/_templates/domain-rule-template.md` 를 읽어 최신 템플릿 형식 파악 +- [ ] `agent-ops/rules/project/domain/` 하위 기존 domain rule 목록을 확인하여 중복·유사 도메인 여부 판단 + +## 실행 절차 + +1. **중복 확인** + - `agent-ops/rules/project/domain//` 폴더 존재 여부 확인 + - 책임이 겹치는 기존 domain rule 이 있으면 사용자에게 알리고 중단한다 + +2. **경로 탐색** + - `path-hints` 가 제공된 경우: 해당 경로를 기준으로 폴더 구조 확인 + - `path-hints` 가 없는 경우: `domain-name` 과 연관된 폴더명·파일명으로 프로젝트를 탐색 + - 실제로 존재하는 경로만 포함 경로에 기재한다 + - 존재하지 않는 경로는 기재하지 않는다 + +3. **도메인 분석** + - 탐색된 경로의 주요 파일·모듈을 읽어 아래를 도출한다 + - 도메인의 목적 / 책임 한 줄 요약 + - 포함 경로 목록 + - 제외 경로 (인접 도메인과 겹칠 수 있는 경로) + - 주요 구성 요소 (파일, 모듈, 클래스, 함수 등) + - 유지할 패턴 (네이밍 규칙, 아키텍처 패턴 등) + - 다른 도메인과의 경계 + - 금지 사항 + +4. **도메인 rules.md 생성** + - 경로: `agent-ops/rules/project/domain//rules.md` + - `domain-rule-template.md` 형식을 따른다 + - 실제 코드에서 확인된 내용만 기재한다 + - 불확실한 항목은 `` 주석으로 남긴다 + +5. **rules/project/rules.md 업데이트** + - `agent-ops/rules/project/rules.md` 를 읽는다 + - 도메인 매핑 테이블에 아래 형식으로 추가한다 + ``` + | `` | `agent-ops/rules/project/domain//rules.md` | + ``` + - 경로 패턴은 실제 포함 경로를 기준으로 작성한다 + - 기존 테이블 항목을 삭제하거나 재정렬하지 않는다 + +6. **결과 보고** + - 생성한 파일 경로 + - rules/project/rules.md 에 추가한 항목 + - 불확실하여 TODO로 남긴 항목 (해당 시) + +## 출력 형식 + +``` +## 생성 완료 + +- Domain Rule 경로: agent-ops/rules/project/domain//rules.md +- 도메인 유형: +- rules/project/rules.md 추가 경로 패턴: + +## TODO 항목 (확인 필요) +- <불확실하여 직접 확인이 필요한 항목> (해당 시) +``` + +## 실행 결과 검증 + +- [ ] `agent-ops/rules/project/domain//rules.md` 파일이 생성되었는가 +- [ ] 생성된 파일이 `domain-rule-template.md`의 모든 섹션(목적, 포함 경로, 제외 경로, 주요 구성 요소, 유지할 패턴, 경계, 금지 사항)을 포함하는가 +- [ ] `rules/project/rules.md`의 도메인 매핑 테이블에 해당 도메인 항목이 추가되었는가 +- [ ] 포함 경로에 기재된 경로가 실제로 프로젝트에 존재하는가 +- 검증 실패 시: 누락된 섹션 또는 잘못된 경로를 사용자에게 알리고 해당 부분만 보완한다 + +## 금지 사항 + +- 이미 존재하는 rules.md 를 덮어쓰지 않는다 +- 실제 존재하지 않는 경로를 포함 경로에 넣지 않는다 +- 추측으로 패턴이나 금지 사항을 채우지 않는다 — 확인된 내용만 기재한다 +- rules/project/rules.md 의 기존 항목을 삭제하거나 재정렬하지 않는다 +- 하나의 domain rule 에 여러 독립 도메인의 책임을 묶지 않는다 +- 코드 변경을 수행하지 않는다 — 이 skill 은 rule 파일 생성만 담당한다 diff --git a/agent-ops/skills/common/create-skill/SKILL.md b/agent-ops/skills/common/create-skill/SKILL.md new file mode 100644 index 0000000..07bb36c --- /dev/null +++ b/agent-ops/skills/common/create-skill/SKILL.md @@ -0,0 +1,95 @@ +--- +name: create-skill +version: 1.0.0 +description: 새로운 SKILL.md 파일을 생성하기 위한 범용 스킬 +--- + +# Create Skill + +## 목적 + +`agent-ops/skills/` 하위에 올바른 형식의 SKILL.md 파일을 생성한다. +기존 skill-template.md 를 기반으로, 요청 목적에 맞는 내용을 채워 넣는다. +생성 후 라우팅 항목을 추가한다. + +### 생성 위치 결정 +- `.agent-ops-source` 파일이 **있으면** (공통 관리 레포): `agent-ops/skills/common//SKILL.md` +- `.agent-ops-source` 파일이 **없으면** (타겟 프로젝트): `agent-ops/skills/project//SKILL.md` + +## 언제 호출할지 + +- 새로운 반복 작업 패턴이 생겨 skill로 정의해야 할 때 +- 기존 skill이 없는 작업 유형을 처음 수행하기 전에 +- 사용자가 특정 작업을 skill로 만들어 달라고 요청할 때 + +## 입력 + +- `skill-name`: 생성할 skill 이름, kebab-case (필수) +- `purpose`: 이 skill이 해결하는 문제 한 줄 요약 (필수) +- `trigger-cases`: 이 skill을 호출해야 하는 상황 목록 (선택) + +## 먼저 확인할 것 + +- [ ] `agent-ops/skills/common/` 및 `agent-ops/skills/project/` 하위에 동일 이름의 디렉터리가 이미 존재하는지 확인 +- [ ] `agent-ops/rules/common/rules.md` 및 `agent-ops/rules/project/rules.md` 에 이미 유사한 라우팅 항목이 있는지 확인 +- [ ] `agent-ops/skills/common/_templates/skill-template.md` 를 읽어 최신 템플릿 형식 파악 + +## 실행 절차 + +1. **중복 확인** + - `agent-ops/skills/common//` 및 `agent-ops/skills/project//` 폴더 존재 여부 확인 + - 기능이 겹치는 기존 skill이 있으면 사용자에게 알리고 중단한다 + +2. **목적 분석** + - `purpose` 와 `trigger-cases` 를 바탕으로 아래 항목을 도출한다 + - 언제 호출할지 (2~4개) + - 필요한 입력 파라미터 + - 사전 확인 항목 + - 실행 절차 (3~7단계) + - 출력 형식 + - 금지 사항 + +3. **SKILL.md 생성** + - 경로: 생성 위치 결정 규칙에 따라 `common/` 또는 `project/` 하위에 생성 + - `skill-template.md` 형식을 따른다 + - 프로젝트 특화 내용보다 범용 절차를 우선한다 + - 절차는 구체적이되 지나치게 세부 구현을 기술하지 않는다 + +4. **라우팅 업데이트** + - `.agent-ops-source` 마커가 **있으면** (공통 관리 레포): `agent-ops/rules/common/rules.md`에 라우팅 항목 추가 + - `.agent-ops-source` 마커가 **없으면** (타겟 프로젝트): `agent-ops/rules/project/rules.md`의 프로젝트 스킬 라우터 섹션에 라우팅 항목 추가 + - 이 skill이 속할 라우팅 축(구조 분석/코드 변경/흐름 추적 등)을 판단한다 + - 기존 라우팅 구조를 깨지 않는다 + +5. **결과 보고** + - 생성한 파일 경로 + - 라우팅 항목을 추가한 파일과 내용 + - 이 skill이 다루지 않는 범위(필요 시) + +## 출력 형식 + +``` +## 생성 완료 + +- SKILL 경로: agent-ops/skills/{common|project}//SKILL.md +- 라우팅 추가: <대상 파일> → <라우팅 축> → + +## 주의사항 (해당 시) +- <이 skill이 다루지 않는 범위 또는 주의할 점> +``` + +## 실행 결과 검증 + +- [ ] `agent-ops/skills/{common|project}//SKILL.md` 파일이 생성되었는가 +- [ ] 생성된 파일이 `skill-template.md`의 필수 섹션(목적, 언제 호출할지, 실행 절차, 실행 결과 검증, 출력 형식, 금지 사항)을 포함하는가 +- [ ] frontmatter에 name, version, description이 올바르게 기재되었는가 +- [ ] 라우팅 대상 파일에 해당 스킬의 라우팅 항목이 추가되었는가 +- 검증 실패 시: 누락된 섹션 또는 라우팅 항목을 사용자에게 알리고 해당 부분만 보완한다 + +## 금지 사항 + +- 이미 존재하는 skill 을 덮어쓰지 않는다 +- 프로젝트 특화 경로(예: `app/screens/`)를 skill 본문에 하드코딩하지 않는다 +- skill 생성과 무관한 코드 파일을 수정하지 않는다 +- 라우팅 대상 파일의 기존 항목을 삭제하거나 재정렬하지 않는다 +- 하나의 skill 에 여러 독립적인 책임을 묶지 않는다 diff --git a/agent-ops/skills/common/init-agent-ops/SKILL.md b/agent-ops/skills/common/init-agent-ops/SKILL.md new file mode 100644 index 0000000..c105459 --- /dev/null +++ b/agent-ops/skills/common/init-agent-ops/SKILL.md @@ -0,0 +1,220 @@ +--- +name: init-agent-ops +version: 1.1.0 +description: 프로젝트 상태를 판별하고 agent-ops 기본 스캐폴드를 생성하기 위한 초기 규칙 +--- + +# init-agent-ops + +## 목적 + +프로젝트에 Agent-Ops 구조가 없거나 불완전할 때, +현재 프로젝트 상태를 분석하여 다음을 세팅한다. + +1. 에이전트 진입 파일 +2. agent-ops 기본 폴더 구조 +3. rules/project/rules.md (프로젝트 특화 규칙, 분석 후 생성) +4. 초기 domain rule 초안 +5. 초기 skill (필요 시) + +"현재 프로젝트에 맞는 최소 스캐폴드" 생성을 우선한다. + +## 언제 호출할지 + +- 프로젝트에 agent-ops 구조가 없을 때 +- agent-ops 구조가 불완전하여 재설정이 필요할 때 +- 사용자가 "agent-ops 초기화해줘", "에이전트 설정해줘" 요청 시 + +## 입력 + +- `project-type`: 신규 / 운영중 (선택, 미지정 시 자동 판별) + +## 먼저 확인할 것 + +- [ ] 프로젝트 루트에 기존 agent-ops 관련 파일(`CLAUDE.md`, `agent-ops/` 등)이 있는지 확인 +- [ ] `.agent-ops-source` 파일이 있는지 확인 (공통 관리 레포 여부) +- [ ] 기존 진입 파일(`CLAUDE.md`, `GEMINI.md` 등)이 있는지 확인 + +## 핵심 원칙 + +- 기존 구조를 우선한다. +- 새 파일 생성은 꼭 필요한 최소 범위로 제한한다. +- 도메인은 발명하지 말고 현재 구조에서 발견한다. +- 처음에는 핵심 도메인만 생성한다. +- 반복되는 작업만 초기 skill로 만든다. +- 불확실한 내용은 후보로 제시한다. + +## 상태 판별 + +### 신규 프로젝트 +- 코드/폴더 구조가 단순하다 +- 도메인 경계가 아직 약하다 +- Agent-Ops 관련 파일이 없다 + +### 운영중 프로젝트 +- 모듈/폴더/패키지 경계가 보인다 +- 반복 작업이 드러난다 +- 핵심 책임 경계가 식별된다 + +## 생성 대상 + +| 파일 | 방법 | +|------|------| +| `CLAUDE.md`,`GEMINI.md`,`AGENTS.md`, `.cursorrules`, `.clinerules` 등 진입 파일 | `rules/common/rules.md`를 에이전트별 파일명으로 프로젝트 루트에 복사 후 `rules/common/rules.md` 삭제 | +| `agent-ops/.version` | 공통 관리 레포의 VERSION 파일을 그대로 복사 (프레임워크 버전 추적용) | +| `agent-ops/rules/common/` | 공통 폴더 전체 복사 (수정 금지) | +| `agent-ops/skills/common/` | 공통 폴더 전체 복사 (수정 금지) | +| `agent-ops/rules/project/rules.md` | 프로젝트 분석 후 생성 | +| `agent-ops/rules/project/domain//rules.md` | 도메인 분석 후 생성 | +| `agent-ops/rules/private/` | 폴더만 생성 (내용은 개인이 작성) | +| `.gitignore`에 `agent-ops/rules/private/` 추가 | git 추적 제외 | + +에이전트별 파일명: + +| 에이전트 | 파일명 | +|---------|--------| +| Claude | `CLAUDE.md` | +| Gemini | `GEMINI.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에는 아래만 둔다. + +- 목적 / 책임 +- 포함 경로 +- 제외 경로 +- 주요 구성 요소 +- 유지할 패턴 +- 다른 도메인과의 경계 +- 금지 사항 + +## DDD 기준 + +- **Core Domain**: 핵심 가치와 주요 유즈케이스 +- **Supporting Domain**: 핵심 도메인을 지원 +- **Generic / Common**: 여러 도메인이 공통으로 사용 + +도메인은 실제 폴더, 모듈, 패키지, 책임 경계와 연결되어야 한다. + +## 실행 절차 + +1. **상태 판별** + - 프로젝트 구조, 모듈 경계, agent-ops 파일 유무를 분석하여 신규/운영중을 판별한다 + +2. **에이전트 진입 파일 생성** + - `rules/common/rules.md`를 에이전트별 파일명으로 프로젝트 루트에 복사한다 + - 복사 후 `rules/common/rules.md`를 삭제한다 + +3. **agent-ops 폴더 구조 복사** + - 공통 관리 레포의 `agent-ops/` 공통 폴더(rules/common, skills/common)를 복사한다 + - `agent-ops/.version` 파일을 복사한다 + +4. **rules/project/rules.md 생성** + - 프로젝트를 분석하여 응답 언어, 프로젝트 개요, 기술 스택 등을 채운다 + - common/rules.md와 내용이 중복되지 않도록 한다 + +5. **도메인 분석 및 domain rule 생성** + - 신규 프로젝트: 핵심 domain placeholder 2~4개만 제안한다. domain rules를 과도하게 채우지 않는다 + - 운영중 프로젝트: Core/Supporting/Generic 도메인을 식별하고 실제 경로를 반영한 초안을 생성한다 + +6. **초기 skill 제안** + - 신규 프로젝트: 최소 2개만 제안한다 + - 운영중 프로젝트: 반복 작업 기반으로 필요한 skill을 제안한다 + +7. **결과 보고** + - 상태 판별 결과, 생성된 파일 목록, 도메인 제안, skill 제안, 주의사항을 출력한다 + +## 출력 형식 + +### 상태 판별 +- Agent-Ops 상태: 없음 / 부분 적용 / 운영중 +- 프로젝트 상태: 신규 / 운영중 +- 근거: 짧게 요약 + +### 스캐폴드 계획 +- 생성할 파일 +- 바로 채울 파일 +- placeholder로 둘 파일 + +### 도메인 제안 +- Core Domain +- Supporting Domain +- Generic / Common + +### 초기 skill 제안 +- skill 이름 +- 필요한 이유 + +### 주의사항 +- 지금 만들지 말아야 할 것 +- 아직 확정하면 안 되는 것 + +## 실행 결과 검증 + +- [ ] 진입 파일이 프로젝트 루트에 존재하고, 내용이 `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/` 항목이 추가되어 있는가 +- 검증 실패 시: 누락된 파일/항목을 사용자에게 알리고 해당 부분만 보완한다 + +## 금지 사항 + +- 진입 파일에 rules/common/rules.md 외 내용을 추가하지 않는다. +- 실제 구조보다 앞선 추상 구조를 강요하지 않는다. +- 처음부터 많은 domain / skill을 만들지 않는다. +- rules/common/rules.md를 프로젝트에서 직접 수정하지 않는다. +- rules/project/rules.md에 rules/common/rules.md와 중복되는 내용을 넣지 않는다. diff --git a/agent-ops/skills/common/router.md b/agent-ops/skills/common/router.md new file mode 100644 index 0000000..5eea531 --- /dev/null +++ b/agent-ops/skills/common/router.md @@ -0,0 +1,10 @@ +# 공통 스킬 라우터 + +| 요청 키워드 | SKILL.md | +|------------|----------| +| agent-ops 세팅해줘, scaffold 만들어줘, 초기화해줘 | `agent-ops/skills/common/init-agent-ops/SKILL.md` | +| domain rule 만들어줘, rules.md 생성, 새 도메인 규칙 | `agent-ops/skills/common/create-domain-rule/SKILL.md` | +| skill 만들어줘, SKILL.md 생성, 새 스킬 추가 | `agent-ops/skills/common/create-skill/SKILL.md` | +| 커밋해줘, 푸시해줘, commit, push, 반영해줘 | `agent-ops/skills/common/commit-push/SKILL.md` | +| 버전 올려줘, 버전 변경 | `agent-ops/skills/common/version-bump/SKILL.md` | +| agent-ops 업데이트해줘, 진입 파일 재적용해줘 | `agent-ops/skills/common/sync-agent-ops/SKILL.md` | diff --git a/agent-ops/skills/common/sync-agent-ops/SKILL.md b/agent-ops/skills/common/sync-agent-ops/SKILL.md new file mode 100644 index 0000000..ed60346 --- /dev/null +++ b/agent-ops/skills/common/sync-agent-ops/SKILL.md @@ -0,0 +1,68 @@ +--- +name: sync-agent-ops +version: 1.0.0 +description: 공통 관리 레포의 rules/common/rules.md 변경 내용을 진입 파일에 재적용한다. "agent-ops 업데이트해줘", "진입 파일 재적용해줘" 요청 시 사용한다. +--- + +# sync-agent-ops + +## 목적 + +공통 관리 레포에서 `rules/common/rules.md`가 변경됐을 때, +프로젝트 루트의 에이전트 진입 파일들에 변경 내용을 반영한다. + +## 언제 호출할지 + +- 공통 관리 레포에서 `rules/common/`이 업데이트된 후 +- "agent-ops 업데이트해줘", "진입 파일 재적용해줘" 요청 시 +- 진입 파일이 `rules/common/rules.md`와 동기화되지 않은 것이 확인됐을 때 + +## 입력 + +- 없음 (파라미터 없이 실행) + +## 먼저 확인할 것 + +- [ ] `agent-ops/rules/common/rules.md` 파일이 존재하는가 +- [ ] 프로젝트 루트에 진입 파일이 하나 이상 존재하는가 + +## 실행 절차 + +1. `agent-ops/.version` 파일이 있으면 현재 프레임워크 버전을 읽고 출력한다 +2. `agent-ops/rules/common/rules.md`를 읽는다 +3. 프로젝트 루트에 존재하는 진입 파일을 확인한다 +4. 존재하는 진입 파일을 `rules/common/rules.md` 내용으로 덮어쓴다 +5. 결과를 출력한다 + +## 에이전트별 진입 파일 + +| 에이전트 | 파일명 | +|---------|--------| +| Claude | `CLAUDE.md` | +| Gemini | `GEMINI.md` | +| Kilo Code / OpenCode | `AGENTS.md` | +| Cursor | `.cursorrules` | +| Cline | `.clinerules` | + +## 실행 결과 검증 + +- [ ] 덮어쓴 진입 파일의 내용이 `rules/common/rules.md`와 정확히 일치하는가 +- [ ] 기존에 존재하던 진입 파일이 누락 없이 모두 업데이트되었는가 +- 검증 실패 시: 불일치하는 파일명과 차이점을 사용자에게 알린다 + +## 출력 형식 + +``` +## 동기화 완료 + +- 프레임워크 버전: {버전} (해당 시) +- 업데이트된 진입 파일: + - {파일명}: 업데이트 완료 +- 변경 없는 파일: {파일명} (해당 시) +``` + +## 금지 사항 + +- `rules/common/rules.md`를 수정하지 않는다. +- `rules/project/rules.md` 등 다른 파일을 건드리지 않는다. +- 존재하지 않는 진입 파일을 새로 생성하지 않는다. diff --git a/agent-ops/skills/common/version-bump/SKILL.md b/agent-ops/skills/common/version-bump/SKILL.md new file mode 100644 index 0000000..178447c --- /dev/null +++ b/agent-ops/skills/common/version-bump/SKILL.md @@ -0,0 +1,81 @@ +--- +name: version-bump +version: 1.0.0 +description: 프로젝트의 버전 정보를 업데이트한다. "버전 올려줘", "버전 변경" 요청 시 사용한다. +--- + +# version-bump + +## 목적 + +프로젝트의 버전 정보를 관리하며, 요청에 따라 버전을 올리거나 지정된 값으로 변경한다. + +## 언제 호출할지 + +- "버전 올려줘", "버전 변경해줘" 요청 시 +- 릴리스 준비 시 버전 업데이트가 필요할 때 +- patch, minor, major 버전 변경 요청 시 + +## 입력 + +- `version-type`: patch / minor / major 중 하나 (선택, 기본값: patch) +- `version-value`: 직접 지정할 버전 값 (선택, version-type과 배타적) + +## 먼저 확인할 것 + +- [ ] 버전 관리 파일(빌드 설정 또는 패키지 파일)이 프로젝트에 존재하는가 +- [ ] 현재 버전 값을 읽을 수 있는가 + +## 실행 절차 +1. 현재 버전 정보를 읽는다 +2. 사용자에게 변경할 버전을 확인한다 + - 인자 없으면: patch 버전 +1 + - 인자 있으면: 지정된 값으로 변경 +3. 버전 파일의 해당 값을 수정 +4. 변경 결과를 출력 + +## 버전 규칙 + +### 형식 +`major.minor.patch` (예: `1.0.0`) + +### 각 자리 제약 +| 자리 | 최대값 | 제약 | +|------|--------|------| +| major | 제한 없음 | 자유롭게 증가 | +| minor | 999 | 0~999 범위 | +| patch | 999 | 0~999 범위 | + +### 올림(carry) 규칙 +버전을 +1 할 때 해당 자리가 999이면 상위 자리를 올리고 현재 자리를 0으로 초기화한다. + +``` +patch +1 시: + patch < 999 → patch + 1 + patch = 999 → minor + 1, patch = 0 + (minor도 999이면 → major + 1, minor = 0, patch = 0) + +예시: + 1.0.998 → 1.0.999 + 1.0.999 → 1.1.0 + 1.999.999 → 2.0.0 +``` + +## 출력 형식 +``` +버전 업데이트 완료: +- 이전: 1.0.0 +- 이후: 1.0.1 +``` + +## 실행 결과 검증 + +- [ ] 버전 파일을 다시 읽어 변경된 버전 값이 의도한 값과 일치하는가 +- [ ] 버전 형식이 `major.minor.patch` 규칙을 준수하는가 (minor, patch가 0~999 범위) +- 검증 실패 시: 변경 전 버전과 현재 값을 사용자에게 보여주고 수동 확인을 요청한다 + +## 금지 사항 + +- 사용자 확인 없이 버전을 변경하지 않는다 +- 버전 형식(`major.minor.patch`)을 벗어나는 값으로 변경하지 않는다 +- minor, patch 값을 999 초과로 설정하지 않는다 diff --git a/agent-ops/skills/project/.gitkeep b/agent-ops/skills/project/.gitkeep new file mode 100644 index 0000000..e69de29