toki/agentic-framework

Fork 0

toki eb9235b5cf update: agent-ops files and documentation

2026-05-19 10:02:35 +09:00

7.2 KiB

Raw Blame History

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/<name>/rules.md

구성

agent-ops/
├── GUIDE.md                              # 이 파일 (적용 가이드)
├── .version                              # 프레임워크 버전 (타겟 프로젝트 버전 추적용)
├── bin/
│   ├── entry-files.sh                    # 진입 파일 목록의 단일 기준
│   ├── init-agent-ops.sh                 # 초기화 스크립트
│   ├── sync.sh                           # 동기화 스크립트
│   └── bump-version.sh                   # 버전 증가 스크립트
├── rules/
│   ├── common/                           # 공통 규칙 (수정 금지)
│   │   ├── rules.md                      # 공통 규칙 (에이전트 진입 파일로 사용)
│   │   └── _templates/
│   │       └── domain-rule-template.md
│   ├── project/                          # 프로젝트 규칙 (수정 가능)
│   │   ├── rules.md                      # 프로젝트 특화 규칙 (init-agent-ops가 생성)
│   │   └── domain/                       # 도메인별 규칙
│   │       └── <domain-name>/rules.md
│   └── private/                          # 개인 규칙 (git 제외, 선택)
│       └── rules.md
└── skills/
    ├── common/                           # 공통 스킬 (수정 금지)
    │   ├── router.md                     # 공통 스킬 라우터
    │   ├── _templates/
    │   │   └── skill-template.md
    │   ├── init-agent-ops/SKILL.md       # scaffold 초기화
    │   ├── sync-pull/SKILL.md            # framework → 현재 프로젝트 동기화
    │   ├── sync-push/SKILL.md            # 현재 프로젝트/framework push 동기화
    │   ├── commit-push/SKILL.md          # 커밋 & 푸시
    │   ├── create-domain-rule/SKILL.md   # 도메인 규칙 생성
    │   ├── create-skill/SKILL.md         # 스킬 생성
    │   └── update-domain-rule/SKILL.md   # 도메인 규칙 수정
    └── project/                          # 프로젝트 스킬 (수정 가능)
        └── <skill-name>/SKILL.md

적용 방법

1. 복사

이 레포의 agent-ops/ 폴더를 타겟 프로젝트 루트에 복사합니다.

project-root/
├── agent-ops/        ← 복사
└── ...

2. 진입 파일 배치

agent-ops/rules/common/rules.md를 사용하는 에이전트에 맞는 파일명으로 프로젝트 루트에 복사합니다. 실제 생성/동기화 대상 목록은 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`

project-root/
├── CLAUDE.md         ← rules/common/rules.md 복사
├── agent-ops/
└── ...

3. scaffold 스킬 실행

AI 에이전트에게 초기화를 요청합니다.

agent-ops 초기화해줘.

에이전트가 프로젝트 구조를 분석하고 다음을 자동 생성합니다:

rules/project/rules.md — 프로젝트 특화 규칙 (응답 언어, 프로젝트 개요, 기술 스택)
rules/project/domain/<name>/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>/SKILL.md
  → rules/project/rules.md
    → skills/project/<skill>/SKILL.md 또는 rules/project/domain/<name>/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` (프로젝트 스킬)	자유롭게 수정

7.2 KiB Raw Blame History