Agent Context Framework

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

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

구조

agent-ops/
  bin/
    entry-files.sh
    init-agent-ops.sh
    sync.sh
    bump-version.sh
  rules/
    common/
      rules.md
    project/
      rules.md
      domain/<domain-name>/rules.md
    private/
      rules.md
  skills/
    common/
      router.md
      <skill-name>/SKILL.md
    project/
      <skill-name>/SKILL.md
  roadmap/
    ROADMAP.md
    current.md
    milestones/<milestone-slug>.md

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

컨텍스트 로딩

에이전트 진입 파일(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회 읽습니다. 파일이 없으면 무시합니다.

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

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

현재 작업 지점이나 남은 작업 질문은 analyze-roadmap-position 스킬이 current.md, 활성 Milestone 문서, git 상태, 변경 파일을 함께 보고 분석합니다.

공통 스킬

공통 스킬 라우팅은 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	기존 로드맵 상태, Milestone, Phase, 한국어 문서 형식 갱신
analyze-roadmap-position	"지금 작업이 뭐지?" 같은 질문에 활성 Milestone과 코드 상태를 함께 분석
plan	구현 작업용 PLAN-*-G??.md와 CODE_REVIEW-*-G??.md 초안 생성
code-review	plan-code-review 루프의 리뷰, 판정, archive, 후속 plan 생성
commit-push	변경 사항을 한국어 커밋 메시지로 커밋하고 푸시
sync-pull	agentic-framework에서 현재 프로젝트로 agent-ops 내려받기
sync-push	현재 agent-ops를 agentic-framework 또는 대상 프로젝트로 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 형식을 따릅니다. 해야 할 작업은 Milestone 문서의 필수 기능 체크리스트로, 완료 판단 조건은 완료 기준 체크리스트로 관리합니다.

일반 작업에서는 전체 ROADMAP.md를 매번 읽지 않습니다. 먼저 current.md의 활성 Milestone 창을 읽고, 요청 범위와 변경 파일에 맞는 Milestone 문서만 읽습니다.

적용

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

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

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

관리 원칙

• 공통 파일은 agentic-framework에서 수정합니다.
• 대상 프로젝트에서는 rules/project/, rules/private/, skills/project/를 프로젝트에 맞게 수정합니다.
• agent-ops/rules/common/, agent-ops/skills/common/, agent-ops/bin/은 공통 관리 영역입니다.
• 공통 파일 변경 후에는 agent-ops/.version을 함께 관리하고 동기화합니다.

설계 효과

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