Agent Context Framework

AI 에이전트가 매 작업마다 필요한 컨텍스트만 읽도록 agent-ops/ 구조를 제공하는 프레임워크입니다.

핵심은 하나의 거대한 규칙 파일을 항상 읽는 방식이 아니라, 진입 규칙에서 프로젝트 규칙, 도메인 규칙, 스킬, 로드맵 문서를 필요한 순간에만 연결하는 것입니다.

현재 상태

이 저장소는 agent-ops/ 공통 파일의 원본 저장소입니다. 루트의 .agent-ops-source 마커가 있으므로 공통 규칙, 공통 스킬, 동기화 스크립트는 이 저장소에서 수정하고 다른 프로젝트로 배포합니다.

현재 프레임워크 버전은 agent-ops/.version에 기록되며, 이 README를 갱신한 시점의 버전은 1.1.126입니다. 이 저장소는 애플리케이션 런타임이 아니라 문서와 셸 스크립트 중심의 프레임워크라서 별도의 빌드나 테스트 설정 파일은 없습니다.

빠른 시작

대상 프로젝트에 공통 scaffold를 직접 배치하려면 이 저장소 루트에서 아래 명령을 실행합니다.

bash agent-ops/bin/init-agent-ops.sh /path/to/target-project

프로젝트 분석을 포함한 초기 세팅은 에이전트에게 정확한 스킬 경로를 지정해 요청합니다. 초기 세팅 전에는 진입 파일이 없을 수 있으므로 스킬 파일 경로를 직접 안내하는 편이 안전합니다.

agent-ops/skills/common/init-agent-ops/SKILL.md 를 읽고 실행해줘.

스킬 실행 후에는 생성된 agent-ops/rules/project/rules.md와 agent-ops/rules/project/domain/*/rules.md를 프로젝트에 맞게 확인하고 보완합니다.

주요 명령

목적	명령	비고
공통 scaffold 배치	bash agent-ops/bin/init-agent-ops.sh /path/to/target-project	source 저장소에서 대상 프로젝트로 공통 파일과 진입 파일을 배치
전체 sibling 프로젝트로 push 동기화	agent-ops/bin/sync.sh	.agent-ops-source가 있는 원본 repo에서 실행하면 상위 폴더의 agent-ops 적용 프로젝트 전체에 반영
특정 프로젝트로 push 동기화	agent-ops/bin/sync.sh <target>	폴더명, 상대경로, 절대경로 사용 가능
대상 프로젝트에서 공통 원본 repo로 변경 올리기	agent-ops/bin/sync.sh agentic-framework	일반 프로젝트에서 실행
공통 원본 repo에서 대상 프로젝트로 내려받기	agent-ops/bin/sync.sh --pull agentic-framework	일반 프로젝트에서 실행
버전 patch 증가 계산	agent-ops/bin/bump-version.sh <major.minor.patch>	결과 버전만 stdout으로 출력
작업 완료 버전 증가	next="$(agent-ops/bin/bump-version.sh "$(cat agent-ops/.version)")" && printf '%s\n' "$next" > agent-ops/.version	이 프로젝트에서 작업을 하나 완료할 때마다 실행. 단, 현재 프로젝트 루트에 .agent-ops-source가 있고 다른 프로젝트로 agent-ops push 동기화만 수행할 때는 실행하지 않음

구조

agent-ops/
  GUIDE.md
  .version
  bin/
    ai-ignore.sh
    entry-files.sh
    init-agent-ops.sh
    sync.sh
    bump-version.sh
  rules/
    common/
      philosophy.md
      rules.md
      rules-roadmap.md
      _templates/
        domain-rule-template.md
    project/
      rules.md
      domain/<domain-name>/rules.md
    private/
      rules.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
      <skill-name>/SKILL.md
    project/
      <skill-name>/SKILL.md
agent-roadmap/
  ROADMAP.md
  current.md  # local, git ignored
  phase/<phase-slug>/PHASE.md
  phase/<phase-slug>/milestones/<milestone-slug>.md
  archive/phase/<phase-slug>/PHASE.md
  archive/phase/<phase-slug>/milestones/<milestone-slug>.md

agent-roadmap/은 create-roadmap 실행 시 생성됩니다.

진입 파일

agent-ops/bin/entry-files.sh가 초기화와 동기화에서 사용하는 진입 파일 목록의 단일 기준입니다.

에이전트	파일
Gemini	GEMINI.md
Claude	CLAUDE.md
Kilo Code / OpenCode	AGENTS.md
Cursor	.cursorrules
Cline	.clinerules

각 진입 파일은 agent-ops/rules/common/rules.md의 복사본입니다. 동기화 시 대상 프로젝트의 기존 진입 파일 내용은 공통 규칙 내용으로 다시 적용됩니다.

컨텍스트 로딩

에이전트 진입 파일(CLAUDE.md, AGENTS.md, GEMINI.md 등)은 agent-ops/rules/common/rules.md의 복사본입니다.

세션이 시작되면 에이전트는 프로젝트별 규칙인 agent-ops/rules/project/rules.md와 개인 규칙인 agent-ops/rules/private/rules.md를 1회 읽습니다. 파일이 없으면 무시합니다.

프로젝트에 agent-roadmap/이 있으면 세션 최초 1회 agent-ops/rules/common/rules-roadmap.md도 읽습니다.

작업이 특정 코드 영역을 변경하면 rules/project/rules.md의 도메인 매핑을 기준으로 해당 rules/project/domain/<domain>/rules.md만 읽습니다.

스킬성 요청은 사용자가 명시적으로 요청했을 때 agent-ops/skills/common/router.md를 읽고, 매핑된 SKILL.md 하나를 실행합니다. 일반 작업마다 router와 모든 스킬을 자동으로 읽지 않습니다.

현재 작업 지점 질문은 analyze-roadmap-position 스킬이 로컬 current.md, ROADMAP.md의 Phase 흐름, 활성 Phase의 Milestone 흐름을 읽고 로드맵 > Phase > Milestone breadcrumb로 빠르게 표시합니다. 기본 동작에서는 코드, git 상태, diff를 읽지 않습니다.

agent-task/archive/**는 완료된 task 산출물이고, agent-roadmap/archive/**는 완료 또는 폐기되어 현재 작업 후보에서 제외한 과거 Milestone 기록입니다. 일반 작업과 로드맵 분석에서는 읽지 않고, 사용자가 과거 기록 확인, 복원, 비교를 요청했거나 active plan/review가 특정 archive evidence 경로를 명시한 경우에만 해당 파일을 좁게 참조합니다.

설계 철학

agent-ops는 AI-first 작업 프레임워크입니다. 규칙, 스킬, 로드맵은 에이전트가 필요한 것만 읽고 바로 행동할 수 있게 짧고 명확해야 합니다.

세부 원칙은 agent-ops/rules/common/philosophy.md에서 관리합니다. 이 문서는 일반 작업 진입점이 아니라, agent-ops 구조나 책임 경계를 설계하고 수정할 때만 읽는 참조 문서입니다.

공통 스킬

공통 스킬 라우팅은 agent-ops/skills/common/router.md가 단일 기준입니다.

스킬	역할
init-agent-ops	대상 프로젝트에 agent-ops 기본 구조, 진입 파일, 프로젝트 규칙, 도메인 규칙 초안을 생성
create-domain-rule	새 도메인 rules.md를 만들고 프로젝트 도메인 매핑에 추가
update-domain-rule	기존 도메인 rules.md를 코드 현황에 맞게 갱신
create-skill	새 공통 또는 프로젝트 스킬 생성
create-readme	AI가 다음 작업에 활용할 수 있는 표준형 README 생성
create-roadmap	한국어 기반 Goal/Phase/Milestone 로드맵 생성
update-roadmap	로드맵 변경 제안, 문서 형식 갱신, Core/MCP action이 없는 경우의 file-based fallback 갱신
analyze-roadmap-position	"지금 작업이 뭐지?" 같은 질문에 전체 로드맵상 현재 Phase/Milestone 좌표를 빠르게 표시
plan	구현 작업용 PLAN-*-G??.md와 CODE_REVIEW-*-G??.md 초안 생성
code-review	plan-code-review 루프의 리뷰, 판정, archive, 후속 plan 생성
commit-push	변경 사항을 한국어 커밋 메시지로 커밋하고 푸시
sync-pull	공통 원본 repo에서 현재 프로젝트로 agent-ops 내려받기
sync-push	현재 agent-ops를 공통 원본 repo 또는 대상 프로젝트로 push 동기화

로드맵

로드맵은 사람이 함께 검토하고 수정하는 협업 문서이므로 전체 구성과 설명 문장은 한국어로 작성합니다.

Goal, Phase, Milestone, API, CLI 같은 일반 개발 용어와 파일명, 경로, slug 같은 식별자는 영어 또는 숫자를 유지할 수 있습니다.

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

로드맵 문서는 agent-ops/skills/common/_templates/roadmap-template.md, roadmap-current-template.md, roadmap-milestone-template.md 형식을 따릅니다. 로컬 agent-roadmap/current.md는 roadmap-current-template.md 형식으로 만들며 git 추적 대상이 아닙니다. 해야 할 작업은 Milestone 문서의 기능 체크리스트로 관리하고, 완료 판단 조건은 필요한 Task 안의 검증: 문구로 흡수합니다.

로드맵 스킬은 문서 작성, 의미 판단, 배치 제안, file-based fallback 갱신을 담당합니다. Core/MCP가 있는 프로젝트에서는 상태 전환, archive 이동, 외부 의존 lock 동기화, 완료 이벤트 반영 같은 action을 Core/MCP 또는 런타임이 처리합니다.

현재 작업 지점 답변은 agent-ops/skills/common/_templates/roadmap-position-report-template.md 형식을 따릅니다.

로드맵 현지점 확인에서는 로컬 current.md, ROADMAP.md의 Phase 흐름, 활성 Phase의 Milestone 흐름, 활성 Milestone의 제목/목표/상태만 기본으로 읽습니다.

완료 또는 폐기되어 현재 후보에서 제외할 과거 Phase/Milestone은 agent-roadmap/archive/phase/<phase-slug>/로 이동합니다. 이때 활성 ROADMAP.md 또는 PHASE.md에는 archive 링크와 짧은 요약만 남기고, 아카이브된 문서는 당시 기록 스냅샷으로 보존하며 최신 스킬 규약에 맞춰 재포맷하지 않습니다.

적용

자세한 적용 절차는 agent-ops/GUIDE.md를 따릅니다.

간단히는 아래 흐름입니다.

1. 이 레포의 agent-ops/ 폴더를 대상 프로젝트 루트에 복사하거나 init-agent-ops.sh로 초기화합니다.
2. 에이전트에게 agent-ops/skills/common/init-agent-ops/SKILL.md 실행을 요청합니다.
3. 생성된 rules/project/rules.md와 도메인 규칙을 확인하고 보완합니다.
4. 반복 작업은 공통 스킬 또는 프로젝트 스킬로 정의합니다.
5. 공통 파일 변경은 .agent-ops-source가 있는 공통 원본 repo에서 관리하고 sync-push / sync-pull로 동기화합니다.

초기화와 .agent-ops-source가 있는 공통 원본 repo에서 일반 프로젝트로 내려가는 동기화는 agent-task/archive/**와 agent-roadmap/archive/**를 에이전트가 기본적으로 읽지 않도록 각 도구별 ignore 또는 watcher ignore 파일도 함께 보강합니다. 단, 두 archive 모두 필요 시 명시 경로로 읽을 수 있어야 하므로 hard read/glob deny가 아니라 ignore 또는 watcher ignore 기준으로만 관리합니다.

동기화 흐름

agent-ops/bin/sync.sh는 현재 프로젝트가 .agent-ops-source를 가진 원본인지 여부에 따라 방향을 결정합니다.

실행 위치	명령	방향
공통 원본 repo	agent-ops/bin/sync.sh	원본에서 sibling 프로젝트 전체로 push
공통 원본 repo	agent-ops/bin/sync.sh <target>	원본에서 특정 대상 프로젝트로 push
일반 프로젝트	agent-ops/bin/sync.sh	현재 프로젝트의 공통 변경을 sibling 공통 원본 repo로 push
일반 프로젝트	agent-ops/bin/sync.sh --pull agentic-framework	공통 원본 repo의 공통 파일을 현재 프로젝트로 pull

push 대상은 agent-ops/.version, agent-ops/bin, agent-ops/rules/common, agent-ops/skills/common, entry-files.sh에 정의된 진입 파일로 제한됩니다. 단, .agent-ops-source가 있는 공통 원본 repo에서 일반 프로젝트로 내려보내는 push에서는 대상 프로젝트의 AI ignore / permission 파일을 덮어쓰지 않고 누락된 표준 설정만 보강하며, 이미 추적 중인 agent-roadmap/current.md는 파일을 보존한 채 git 추적에서 제거합니다. 버전을 올리지 않고 현재 agent-ops/.version 값을 그대로 전파합니다. 일반 프로젝트에서 공통 원본 repo로 올리는 push에서는 AI ignore / permission 파일을 보강하거나 stage하지 않으며, 공통 변경이 있으면 버전을 한 단계 올립니다.

관리 원칙

• 공통 파일은 .agent-ops-source가 있는 공통 원본 repo에서 수정합니다.
• 대상 프로젝트에서는 rules/project/, rules/private/, skills/project/를 프로젝트에 맞게 수정합니다.
• agent-ops/rules/common/, agent-ops/skills/common/, agent-ops/bin/은 공통 관리 영역입니다.
• 공통 파일 변경 후에는 agent-ops/.version을 함께 관리하고 동기화합니다.
• 이 프로젝트에서 작업을 하나 완료할 때마다 agent-ops/bin/bump-version.sh로 agent-ops/.version을 한 단계 올립니다. 단, 현재 프로젝트 루트에 .agent-ops-source가 있고 다른 프로젝트로 agent-ops push 동기화만 수행하는 작업에서는 버전을 올리지 않습니다.
• agent-ops/rules/private/는 개인 규칙 영역이며 대상 프로젝트의 .gitignore에 추가됩니다.
• agent-roadmap/current.md는 브랜치별 로컬 로드맵 포인터이며 .gitignore로 추적 제외합니다. 초기 형식은 agent-ops/skills/common/_templates/roadmap-current-template.md를 사용합니다.

작업 맥락

AI 에이전트가 이 저장소를 이어서 작업할 때는 아래 경로를 먼저 확인하면 됩니다.

경로	역할
agent-ops/rules/common/rules.md	모든 에이전트 진입 파일의 원본
agent-ops/rules/common/philosophy.md	agent-ops 구조와 문서 작성 원칙
agent-ops/rules/common/rules-roadmap.md	로드맵 사용 프로젝트의 추가 공통 규칙
agent-ops/skills/common/router.md	요청 키워드와 공통 스킬 매핑
agent-ops/skills/common/*/SKILL.md	반복 작업별 실행 절차
agent-ops/bin/entry-files.sh	진입 파일 목록의 단일 기준
agent-ops/bin/sync.sh	공통 파일 push/pull 동기화 구현
agent-ops/GUIDE.md	대상 프로젝트 적용 가이드

설계 효과

항목	내용
선택적 컨텍스트	작업에 필요한 규칙과 스킬만 읽어 컨텍스트 낭비를 줄임
프로젝트 적응	프로젝트별 규칙과 도메인 규칙으로 코드베이스별 차이를 반영
반복 작업 표준화	초기화, 도메인 규칙, 로드맵, 계획, 리뷰, 커밋, 동기화를 스킬로 고정
추적 가능성	rules, skills, roadmap을 레포에서 버전 관리
확장성	공통 스킬과 프로젝트 스킬을 분리해 팀 표준과 프로젝트 특화를 함께 운영