toki/agentic-framework

Fork 0

toki 520fedd0b4 Simplify roadmap lock approval flow

2026-05-24 16:21:00 +09:00

10 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                    # 진입 파일 목록의 단일 기준
│   ├── ai-ignore.sh                      # AI ignore / permission 기본 설정
│   ├── 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
├── roadmap/                              # 프로젝트 로드맵 (create-roadmap 실행 시 생성)
│   ├── ROADMAP.md
│   ├── current.md
│   ├── milestones/
│   │   └── <milestone-slug>.md
│   └── archive/
│       └── YYYY/MM/<milestone-slug>.md
└── skills/
    ├── common/                           # 공통 스킬 (수정 금지)
    │   ├── router.md                     # 공통 스킬 라우터
    │   ├── _templates/
    │   │   ├── skill-template.md
    │   │   ├── roadmap-template.md
    │   │   ├── roadmap-current-template.md
    │   │   ├── roadmap-milestone-template.md
    │   │   └── roadmap-position-report-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         # 스킬 생성
    │   ├── create-readme/SKILL.md        # README 생성
    │   ├── create-roadmap/SKILL.md       # Goal/Phase/Milestone 로드맵 생성
    │   ├── update-roadmap/SKILL.md       # 로드맵 상태/마일스톤 갱신과 아카이빙
    │   ├── analyze-roadmap-position/SKILL.md # 현재 작업 지점/남은 작업 분석
    │   └── update-domain-rule/SKILL.md   # 도메인 규칙 수정
    └── project/                          # 프로젝트 스킬 (수정 가능)
        └── <skill-name>/SKILL.md

로드맵 문서는 사람이 함께 검토하고 수정하는 협업 문서이므로 전체 구성과 설명 문장을 기본 한국어로 작성합니다. Goal, Phase, Milestone, API 같은 일반 개발 용어와 파일명, 경로, slug 같은 식별자는 영어 또는 숫자를 유지할 수 있습니다.

Phase와 Milestone에는 순번을 강제하지 않습니다. 진행 순서는 ROADMAP.md에 적힌 위에서 아래 순서로 봅니다. 새 작업을 추가할 때는 사용자가 지정한 위치를 우선하고, 단위 지정이 없으면 작업 성격을 보고 새 Milestone, 기존 Milestone의 태스크, 기존 태스크의 하위 작업 중 적절한 단위로 배치합니다.

로드맵 문서는 agent-ops/skills/common/_templates/roadmap-template.md, roadmap-current-template.md, roadmap-milestone-template.md 형식을 기준으로 작성합니다. 해야 할 작업은 Milestone 문서의 필수 기능 체크리스트로 두고, 완료 여부를 검증하는 조건은 완료 기준 체크리스트로 둡니다.

Milestone의 구현 잠금은 사용자 승인 없이 구현으로 내려가지 않기 위한 상태 기록입니다. 사용자가 해당 Milestone의 작업, 구현, 계획 작성, 또는 잠금 해제를 명시하면 추가 체크리스트 없이 해제 승인으로 보고, 구현 잠금 상태와 해제 근거만 갱신합니다. 이때 필수 기능이나 완료 기준은 자동 완료 처리하지 않습니다.

현재 작업 지점/남은 작업 분석 답변은 agent-ops/skills/common/_templates/roadmap-position-report-template.md 형식을 기준으로 작성합니다.

완료 또는 폐기되어 현재 작업 후보에서 제외할 과거 Milestone은 agent-ops/roadmap/archive/YYYY/MM/로 이동합니다. 이때 ROADMAP.md에는 아카이브 Milestone 요약만 남기고, 아카이브 문서는 사용자가 과거 기록 확인이나 복원을 명시적으로 요청한 경우에만 읽습니다.

적용 방법

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` (프로젝트 스킬)	자유롭게 수정

10 KiB Raw Blame History