update: agent-ops files and documentation

2026-05-19 10:02:35 +09:00 · 2026-05-19 10:02:35 +09:00 · eb9235b5cf
commit eb9235b5cf
parent 62f4bdd916
8 changed files with 79 additions and 50 deletions
--- 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 제외)

 구조는 공통이고, 내용은 프로젝트마다 다르다.
--- 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-name>/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` |
--- a/agent-ops/bin/entry-files.sh
+++ 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
+}
--- 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 <target_directory>"
    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"
--- 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] <target>"
@ -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
--- 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`의 도메인 매핑 테이블에 생성된 도메인이 모두 등록되어 있는가
--- 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 <target>

 - [ ] sync.sh 가 오류 없이 완료됐는가
 - [ ] 현재 프로젝트 버전이 framework 버전과 일치하는가
- [ ] 진입 파일(CLAUDE.md 등)이 갱신됐는가
+- [ ] `agent-ops/bin/entry-files.sh`의 모든 진입 파일이 갱신됐고, 내용이 framework의 `agent-ops/rules/common/rules.md`와 일치하는가

 ## 금지 사항

--- 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 <target>` 실행
 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 <target>
@ -37,6 +53,7 @@ agent-ops/bin/sync.sh <target>

 - [ ] sync.sh 가 오류 없이 완료됐는가
 - [ ] 버전 충돌 경고가 없었는가 — 있었다면 사용자에게 수동 머지 필요함을 알린다
+- [ ] agentic-framework에서 대상 프로젝트로 push한 경우, `agent-ops/bin/entry-files.sh`의 모든 진입 파일 내용이 현재 agentic-framework의 `agent-ops/rules/common/rules.md`와 일치하는가

 ## 금지 사항