From eb9235b5cf51e6e597f8a957d6b8f635d110f7b7 Mon Sep 17 00:00:00 2001 From: toki Date: Tue, 19 May 2026 10:02:35 +0900 Subject: [PATCH] update: agent-ops files and documentation --- README.md | 4 +- agent-ops/GUIDE.md | 13 +++++-- agent-ops/bin/entry-files.sh | 24 ++++++++++++ agent-ops/bin/init-agent-ops.sh | 13 ++++--- agent-ops/bin/sync.sh | 38 ++++--------------- .../skills/common/init-agent-ops/SKILL.md | 14 ++++--- agent-ops/skills/common/sync-pull/SKILL.md | 2 +- agent-ops/skills/common/sync-push/SKILL.md | 21 +++++++++- 8 files changed, 79 insertions(+), 50 deletions(-) create mode 100644 agent-ops/bin/entry-files.sh diff --git a/README.md b/README.md index 1ebdd9e..0ad2a61 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,8 @@ LLM의 컨텍스트 윈도우는 유한하다. 관련 없는 내용이 많을수 ``` agent-ops/ + ├── bin/ + │ └── entry-files.sh # 진입 파일 목록의 단일 기준 ├── rules/ │ ├── common/ │ │ └── rules.md # 진입 파일 템플릿 (에이전트별 파일명으로 복사) @@ -201,7 +203,7 @@ project/rules.md의 도메인 매핑 테이블이 경로 패턴과 domain/rules. 3. 도메인별 rules.md 작성 4. 반복 작업을 SKILL.md로 정의 5. router.md에 작업 유형별 매핑 등록 -6. rules/common/rules.md 내용을 에이전트별 파일명으로 진입 파일 생성 (CLAUDE.md 등) +6. rules/common/rules.md 내용을 `agent-ops/bin/entry-files.sh`의 파일 목록으로 진입 파일 생성 7. (선택) rules/private/rules.md에 개인 규칙 작성 (git 제외) 구조는 공통이고, 내용은 프로젝트마다 다르다. diff --git a/agent-ops/GUIDE.md b/agent-ops/GUIDE.md index 17afb98..dbff897 100644 --- a/agent-ops/GUIDE.md +++ b/agent-ops/GUIDE.md @@ -29,6 +29,11 @@ agent-ops/skills/common/init-agent-ops/SKILL.md 를 읽고 실행해줘. agent-ops/ ├── GUIDE.md # 이 파일 (적용 가이드) ├── .version # 프레임워크 버전 (타겟 프로젝트 버전 추적용) +├── bin/ +│ ├── entry-files.sh # 진입 파일 목록의 단일 기준 +│ ├── init-agent-ops.sh # 초기화 스크립트 +│ ├── sync.sh # 동기화 스크립트 +│ └── bump-version.sh # 버전 증가 스크립트 ├── rules/ │ ├── common/ # 공통 규칙 (수정 금지) │ │ ├── rules.md # 공통 규칙 (에이전트 진입 파일로 사용) @@ -46,11 +51,12 @@ agent-ops/ │ ├── _templates/ │ │ └── skill-template.md │ ├── init-agent-ops/SKILL.md # scaffold 초기화 - │ ├── sync-agent-ops/SKILL.md # 진입 파일 재적용 + │ ├── sync-pull/SKILL.md # framework → 현재 프로젝트 동기화 + │ ├── sync-push/SKILL.md # 현재 프로젝트/framework push 동기화 │ ├── commit-push/SKILL.md # 커밋 & 푸시 │ ├── create-domain-rule/SKILL.md # 도메인 규칙 생성 │ ├── create-skill/SKILL.md # 스킬 생성 - │ └── version-bump/SKILL.md # 버전 업데이트 + │ └── update-domain-rule/SKILL.md # 도메인 규칙 수정 └── project/ # 프로젝트 스킬 (수정 가능) └── /SKILL.md ``` @@ -72,11 +78,12 @@ project-root/ ### 2. 진입 파일 배치 `agent-ops/rules/common/rules.md`를 사용하는 에이전트에 맞는 파일명으로 프로젝트 루트에 복사합니다. +실제 생성/동기화 대상 목록은 `agent-ops/bin/entry-files.sh`의 `AGENT_OPS_ENTRY_FILES`를 단일 기준으로 사용합니다. | 에이전트 | 파일명 | |---------|--------| -| Claude | `CLAUDE.md` | | Gemini | `GEMINI.md` | +| Claude | `CLAUDE.md` | | Kilo Code / OpenCode | `AGENTS.md` | | Cursor | `.cursorrules` | | Cline | `.clinerules` | diff --git a/agent-ops/bin/entry-files.sh b/agent-ops/bin/entry-files.sh new file mode 100644 index 0000000..dfb6f90 --- /dev/null +++ b/agent-ops/bin/entry-files.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env bash + +# Shared entry-point file list for init/sync scripts. +AGENT_OPS_ENTRY_FILES=("GEMINI.md" "CLAUDE.md" "AGENTS.md" ".cursorrules" ".clinerules") + +apply_agent_ops_entry_files() { + local rules_md="$1" + local target_root="$2" + + if [[ ! -f "$rules_md" ]]; then + if [[ -n "${YELLOW:-}" && -n "${RESET:-}" ]]; then + echo -e "${YELLOW} rules.md 없음, 진입 파일 재적용 건너뜀${RESET}" + else + echo " rules.md 없음, 진입 파일 재적용 건너뜀" + fi + return + fi + + local f + for f in "${AGENT_OPS_ENTRY_FILES[@]}"; do + cp "$rules_md" "$target_root/$f" + echo " 진입 파일 적용: $f" + done +} diff --git a/agent-ops/bin/init-agent-ops.sh b/agent-ops/bin/init-agent-ops.sh index d66e2ab..449c410 100755 --- a/agent-ops/bin/init-agent-ops.sh +++ b/agent-ops/bin/init-agent-ops.sh @@ -5,13 +5,16 @@ set -e +SCRIPT_DIR=$(realpath "$(dirname "$0")") +SOURCE_DIR=$(realpath "$SCRIPT_DIR/..") +source "$SCRIPT_DIR/entry-files.sh" + if [ -z "$1" ]; then echo "Usage: $0 " exit 1 fi TARGET_DIR=$(realpath "$1") -SOURCE_DIR=$(realpath "$(dirname "$0")/..") ARCHIVE_IGNORE_PATTERN="agent-task/archive/**" append_unique_line() { @@ -34,16 +37,14 @@ mkdir -p "$TARGET_DIR/agent-ops/skills/project" # 2. 공통 요소 복사 (프로젝트 전용 설정은 제외) cp "$SOURCE_DIR/.version" "$TARGET_DIR/agent-ops/" +rm -rf "$TARGET_DIR/agent-ops/bin" +cp -r "$SOURCE_DIR/bin" "$TARGET_DIR/agent-ops/" cp -r "$SOURCE_DIR/rules/common" "$TARGET_DIR/agent-ops/rules/" cp -r "$SOURCE_DIR/skills/common" "$TARGET_DIR/agent-ops/skills/" # 3. 에이전트 진입 파일 생성 (common/rules.md 복사) COMMON_RULES="$SOURCE_DIR/rules/common/rules.md" -cp "$COMMON_RULES" "$TARGET_DIR/GEMINI.md" -cp "$COMMON_RULES" "$TARGET_DIR/CLAUDE.md" -cp "$COMMON_RULES" "$TARGET_DIR/AGENTS.md" -cp "$COMMON_RULES" "$TARGET_DIR/.cursorrules" -cp "$COMMON_RULES" "$TARGET_DIR/.clinerules" +apply_agent_ops_entry_files "$COMMON_RULES" "$TARGET_DIR" # 4. AI ignore / permission 설정 append_unique_line "$TARGET_DIR/.geminiignore" "$ARCHIVE_IGNORE_PATTERN" diff --git a/agent-ops/bin/sync.sh b/agent-ops/bin/sync.sh index d65e10e..632853d 100755 --- a/agent-ops/bin/sync.sh +++ b/agent-ops/bin/sync.sh @@ -9,6 +9,9 @@ PROJECT_ROOT="$(cd "$AGENT_OPS_DIR/.." && pwd)" # ── 색상 ───────────────────────────────────────────────────────────────────── RED='\033[0;31m'; YELLOW='\033[1;33m'; GREEN='\033[0;32m'; RESET='\033[0m' +# ── 진입 파일 공통 관리 ────────────────────────────────────────────────────── +source "$SCRIPT_DIR/entry-files.sh" + # ── 대상 경로 해석 (폴더명 / 상대경로 / 절대경로) ──────────────────────────── resolve_target() { local input="$1" @@ -68,34 +71,6 @@ sync_common() { sync_folder "$src/bin" "$dst/bin" } -# ── rules.md 내용을 진입 파일들에 반영 ─────────────────────────────────────── -apply_entry_files() { - local rules_md="$1" - local target_root="$2" - - if [[ ! -f "$rules_md" ]]; then - echo -e "${YELLOW} rules.md 없음, 진입 파일 재적용 건너뜀${RESET}" - return - fi - - # 기본 자동 생성/갱신 대상 - local default_files=("CLAUDE.md" "GEMINI.md" ".cursorrules" "AGENTS.md") - # 존재할 때만 갱신 - local optional_files=(".clinerules") - - for f in "${default_files[@]}"; do - cp "$rules_md" "$target_root/$f" - echo " 진입 파일 적용: $f" - done - - for f in "${optional_files[@]}"; do - if [[ -f "$target_root/$f" ]]; then - cp "$rules_md" "$target_root/$f" - echo " 진입 파일 적용: $f" - fi - done -} - # ── 사용법 ──────────────────────────────────────────────────────────────────── usage() { echo "사용법: $0 [--pull] " @@ -144,10 +119,10 @@ if [[ "$PULL_MODE" == "1" ]]; then echo " 현재 버전: $SRC_VER | framework 버전: $DST_VER" sync_common "$DST_AO" "$SRC_AO" cp "$DST_AO/.version" "$SRC_AO/.version" - apply_entry_files "$DST_AO/rules/common/rules.md" "$PROJECT_ROOT" + apply_agent_ops_entry_files "$DST_AO/rules/common/rules.md" "$PROJECT_ROOT" cd "$PROJECT_ROOT" git add agent-ops/rules/common agent-ops/skills/common agent-ops/bin agent-ops/.version \ - CLAUDE.md GEMINI.md .cursorrules AGENTS.md + "${AGENT_OPS_ENTRY_FILES[@]}" git commit -m "sync: pull from agentic-framework v$DST_VER" git push echo -e "${GREEN}✓ 완료 (pull v$DST_VER)${RESET}" @@ -161,12 +136,13 @@ if [[ "$IS_FRAMEWORK" == "1" ]]; then if [[ ! -d "$DST_AO" ]]; then echo " 최초 진행: agent-ops 전체 복사" cp -r "$SRC_AO" "$TARGET/" + apply_agent_ops_entry_files "$SRC_AO/rules/common/rules.md" "$TARGET" echo -e "${YELLOW} init-agent-ops 스킬로 초기화를 진행하세요.${RESET}" else echo " 이후 진행: common/ 동기화" sync_common "$SRC_AO" "$DST_AO" cp "$SRC_AO/.version" "$DST_AO/.version" - apply_entry_files "$SRC_AO/rules/common/rules.md" "$TARGET" + apply_agent_ops_entry_files "$SRC_AO/rules/common/rules.md" "$TARGET" fi echo -e "${GREEN}✓ 완료 → $(basename "$TARGET")${RESET}" exit 0 diff --git a/agent-ops/skills/common/init-agent-ops/SKILL.md b/agent-ops/skills/common/init-agent-ops/SKILL.md index 83866f1..af2b836 100644 --- a/agent-ops/skills/common/init-agent-ops/SKILL.md +++ b/agent-ops/skills/common/init-agent-ops/SKILL.md @@ -62,8 +62,9 @@ description: 프로젝트 상태를 판별하고 agent-ops 기본 스캐폴드 | 파일 | 방법 | |------|------| -| `CLAUDE.md`,`GEMINI.md`,`AGENTS.md`, `.cursorrules`, `.clinerules` 등 진입 파일 | `rules/common/rules.md`를 에이전트별 파일명으로 프로젝트 루트에 복사 후 `rules/common/rules.md` 삭제 | +| `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` | 프로젝트 분석 후 생성 | @@ -75,10 +76,12 @@ description: 프로젝트 상태를 판별하고 agent-ops 기본 스캐폴드 에이전트별 파일명: +실제 생성/동기화 대상 목록은 `agent-ops/bin/entry-files.sh`의 `AGENT_OPS_ENTRY_FILES`를 단일 기준으로 사용한다. + | 에이전트 | 파일명 | |---------|--------| -| Claude | `CLAUDE.md` | | Gemini | `GEMINI.md` | +| Claude | `CLAUDE.md` | | Kilo Code / OpenCode | `AGENTS.md` | | Cursor | `.cursorrules` | | Cline | `.clinerules` | @@ -167,8 +170,7 @@ common/rules.md와 내용이 중복되지 않도록 한다. - 프로젝트 구조, 모듈 경계, agent-ops 파일 유무를 분석하여 신규/운영중을 판별한다 2. **에이전트 진입 파일 생성** - - `rules/common/rules.md`를 에이전트별 파일명으로 프로젝트 루트에 복사한다 - - 복사 후 `rules/common/rules.md`를 삭제한다 + - `rules/common/rules.md`를 `agent-ops/bin/entry-files.sh`의 파일 목록으로 프로젝트 루트에 복사한다 3. **AI ignore / permission 기본 설정** - `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에 `agent-task/archive/**`를 추가한다 @@ -176,7 +178,7 @@ common/rules.md와 내용이 중복되지 않도록 한다. - `agent-task/archive/**` 제외는 `.gitignore`에 추가하지 않는다 4. **agent-ops 폴더 구조 복사** - - 공통 관리 레포의 `agent-ops/` 공통 폴더(rules/common, skills/common)를 복사한다 + - 공통 관리 레포의 `agent-ops/` 공통 폴더(bin, rules/common, skills/common)를 복사한다 - `agent-ops/.version` 파일을 복사한다 5. **rules/project/rules.md 생성** @@ -221,7 +223,7 @@ common/rules.md와 내용이 중복되지 않도록 한다. ## 실행 결과 검증 -- [ ] 진입 파일이 프로젝트 루트에 존재하고, 내용이 `rules/common/rules.md`와 일치하는가 +- [ ] `agent-ops/bin/entry-files.sh`의 모든 진입 파일이 프로젝트 루트에 존재하고, 내용이 초기화에 사용한 `rules/common/rules.md`와 일치하는가 - [ ] `agent-ops/rules/project/rules.md`가 생성되었고, 필수 항목(응답 언어, 프로젝트 개요, 기술 스택)이 포함되어 있는가 - [ ] 생성된 domain rules.md가 `domain-rule-template.md` 형식을 따르는가 - [ ] `rules/project/rules.md`의 도메인 매핑 테이블에 생성된 도메인이 모두 등록되어 있는가 diff --git a/agent-ops/skills/common/sync-pull/SKILL.md b/agent-ops/skills/common/sync-pull/SKILL.md index 9afcdb1..adc2c42 100644 --- a/agent-ops/skills/common/sync-pull/SKILL.md +++ b/agent-ops/skills/common/sync-pull/SKILL.md @@ -29,7 +29,7 @@ agent-ops/bin/sync.sh --pull - [ ] sync.sh 가 오류 없이 완료됐는가 - [ ] 현재 프로젝트 버전이 framework 버전과 일치하는가 -- [ ] 진입 파일(CLAUDE.md 등)이 갱신됐는가 +- [ ] `agent-ops/bin/entry-files.sh`의 모든 진입 파일이 갱신됐고, 내용이 framework의 `agent-ops/rules/common/rules.md`와 일치하는가 ## 금지 사항 diff --git a/agent-ops/skills/common/sync-push/SKILL.md b/agent-ops/skills/common/sync-push/SKILL.md index 7f18074..04884a1 100644 --- a/agent-ops/skills/common/sync-push/SKILL.md +++ b/agent-ops/skills/common/sync-push/SKILL.md @@ -1,13 +1,16 @@ --- name: sync-push -description: 현재 프로젝트의 agent-ops를 agentic-framework로 올린다. "agent-ops 싱크해", "agent-ops 동기화해", "agentic-framework에 올려줘" 요청 시 사용한다. +description: 현재 프로젝트의 agent-ops를 agentic-framework로 올리거나, agentic-framework의 공통 agent-ops를 대상 프로젝트로 push한다. "agent-ops 싱크해", "agent-ops 동기화해", "agentic-framework에 올려줘" 요청 시 사용한다. --- # sync-push ## 목적 -`agent-ops/bin/sync.sh`를 호출해 현재 프로젝트 → agentic-framework 방향으로 agent-ops를 올린다. +`agent-ops/bin/sync.sh`를 호출해 agent-ops 공통 파일을 push 방향으로 동기화한다. + +- 일반 프로젝트에서는 현재 프로젝트 → agentic-framework 방향으로 올린다. +- agentic-framework 원본 프로젝트에서는 agentic-framework → 대상 프로젝트 방향으로 보낸다. ## 언제 호출할지 @@ -28,6 +31,19 @@ description: 현재 프로젝트의 agent-ops를 agentic-framework로 올린다. 1. 사용자 요청에서 target 프로젝트명 또는 경로를 추출한다 2. **명시된 경우**: `agent-ops/bin/sync.sh ` 실행 3. **명시되지 않은 경우**: 사용자에게 대상 프로젝트 입력을 요청한다 +4. `sync.sh`는 현재 agentic-framework의 `agent-ops/rules/common/rules.md` 내용을 대상 프로젝트 루트의 진입 파일에 덮어쓴다 + +덮어쓰기 대상은 `init-agent-ops` 초기 세팅과 동일하며, 실제 목록은 `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` | + +대상 프로젝트에 기존 진입 파일이 있어도 보존하거나 병합하지 않고 `agent-ops/rules/common/rules.md` 내용으로 교체한다. ```bash agent-ops/bin/sync.sh @@ -37,6 +53,7 @@ agent-ops/bin/sync.sh - [ ] sync.sh 가 오류 없이 완료됐는가 - [ ] 버전 충돌 경고가 없었는가 — 있었다면 사용자에게 수동 머지 필요함을 알린다 +- [ ] agentic-framework에서 대상 프로젝트로 push한 경우, `agent-ops/bin/entry-files.sh`의 모든 진입 파일 내용이 현재 agentic-framework의 `agent-ops/rules/common/rules.md`와 일치하는가 ## 금지 사항