toki 599ef4026b sync: agent-ops from agentic-framework v1.1.25

2026-05-21 20:22:08 +09:00

9.7 KiB

Raw Blame History

name	version	description
create-roadmap	1.2.0	AI-first 개인/소규모 프로젝트의 전체 목표, Phase, 순번 없는 Milestone 문서, 활성 Milestone 창을 처음 생성하는 공통 스킬

로드맵 생성

목적

agent-ops/roadmap/ 하위에 전체 목표 / Phase / Milestone 기반 한국어 로드맵 구조를 처음 생성한다. 전체 로드맵은 로드맵 설계와 갱신 때만 읽고, 일반 작업에서는 current.md의 활성 Milestone 창과 관련 Milestone 문서만 읽도록 컨텍스트 로딩 규칙을 만든다.

언제 호출할지

프로젝트에 파일 기반 로드맵을 처음 만들 때
사용자가 "로드맵 만들어줘", "마일스톤 설계해줘", "goal/phase 구조 잡아줘"라고 요청할 때
AI-first 개인/소규모 개발 프로젝트의 현재 방향성과 작업 기준을 구조화해야 할 때
기존 README나 메모에 흩어진 계획을 agent-ops/roadmap/ 구조로 분리할 때

입력

overall-goal: 프로젝트 전체 목표 한 줄 또는 짧은 문단 (선택, 없으면 README와 현재 구조에서 추론)
phase-hints: 예상 Phase 목록 또는 단계 힌트 (선택)
milestone-hints: 예상 Milestone 목록 또는 기능 힌트 (선택)
active-milestones: 현재 열어둘 Milestone 목록 (선택, 없으면 현재 구현 상태와 요청에서 추론)

생성 구조

agent-ops/
  roadmap/
    ROADMAP.md
    current.md
    milestones/
      <milestone-slug>.md

파일	역할
`agent-ops/roadmap/ROADMAP.md`	전체 목표, Phase 흐름, 문서 순서 기반 Milestone 목록. 로드맵 생성/갱신/Phase 전환 때만 읽는다
`agent-ops/roadmap/current.md`	지금 열려 있는 활성 Milestone 창과 선택 규칙을 담는 얇은 포인터
`agent-ops/roadmap/milestones/<milestone-slug>.md`	일반 작업 시 읽는 Milestone 단위 목표, 범위, 기능 목록, 범위 제외 항목

작성 언어

agent-ops/roadmap/ 하위 로드맵 문서는 사람이 함께 검토하고 수정하는 협업 문서이므로 기본 작성 언어를 한국어로 한다.
전체 구성, 섹션 제목, 설명 문장, 기능 설명, 완료 기준, TODO, 가정은 한국어 문장으로 작성한다.
Goal, Phase, Milestone, Scope, API, CLI처럼 개발자에게 자연스러운 일반 용어, 파일명, 경로, slug, 코드 식별자는 영어 또는 숫자를 유지할 수 있다.
상태 값은 계획, 진행 중, 완료, 보류, 폐기 중 하나만 사용한다.
프로젝트 규칙에 별도 문서 언어가 명시되어 있으면 그 규칙을 우선하되, 명시가 없으면 한국어를 기본값으로 삼는다.

순서 정책

Phase와 Milestone 이름에 1, 2, M01, P1 같은 순번을 붙이지 않는다.
진행 순서는 ROADMAP.md에 적힌 위에서 아래 순서로만 해석한다.
Milestone 파일명은 순번 없이 agent-ops/roadmap/milestones/<milestone-slug>.md로 만든다.
중간에 Phase나 Milestone을 끼워 넣을 수 있도록 기존 항목의 이름과 파일명을 불필요하게 바꾸지 않는다.

current.md 형식

agent-ops/roadmap/current.md는 아래 형식을 유지한다.

# 현재 로드맵 컨텍스트

## 활성 Milestone

- <milestone-name>: agent-ops/roadmap/milestones/<milestone-slug>.md

## 선택 규칙

- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 Milestone을 선택한다.
- 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다.
- 활성 Milestone 밖의 작업이면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.

current.md는 개인별 작업 위치가 아니라 현재 열어둘 Milestone 후보 목록이다. 실제 현 작업 지점과 남은 작업은 analyze-roadmap-position 스킬이 코드와 git 상태를 함께 읽고 분석한다.

먼저 확인할 것

agent-ops/roadmap/ROADMAP.md 또는 agent-ops/roadmap/current.md가 이미 존재하는지 확인
이미 존재하면 덮어쓰지 말고 update-roadmap 스킬 사용을 안내
README.md, agent-ops/GUIDE.md, agent-ops/rules/project/rules.md 등 프로젝트 방향을 설명하는 문서를 확인
rg --files로 현재 프로젝트의 주요 구조를 가볍게 확인
agent-ops/rules/project/rules.md가 있으면 마일스톤 컨텍스트 로딩 섹션 추가 위치 확인

실행 절차

기존 로드맵 확인
- agent-ops/roadmap/ 하위 기존 파일 존재 여부를 확인한다.
- 기존 로드맵이 있으면 새로 만들지 않고 update-roadmap을 사용하도록 안내한다.
- 일부 파일만 있으면 누락 파일을 보완할지, 기존 구조를 유지할지 사용자에게 짧게 확인한다.
프로젝트 방향 분석
- README와 프로젝트 규칙에서 대상 사용자, 해결하려는 문제, 현재 구현 상태를 파악한다.
- 전체 코드를 정독하지 않는다. 로드맵 설계에 필요한 문서와 상위 구조만 확인한다.
- 불확실한 제품 방향은 단정하지 않고 "가정" 또는 로 남긴다.
목표 / Phase / Milestone 설계
- 전체 목표는 프로젝트가 궁극적으로 만들려는 결과를 1~3문장으로 작성한다.
- Phase는 큰 진화 단위로 나누고, 각 Phase에 목표를 둔다.
- Milestone은 Phase 안에서 완료 판단이 가능한 단위로 나눈다.
- Phase와 Milestone은 순번 없이 이름으로만 작성하고, 순서는 문서의 위에서 아래 흐름으로 표현한다.
- 상태 값은 계획, 진행 중, 완료, 보류, 폐기 중 하나만 사용한다.
로드맵 파일 생성
- agent-ops/roadmap/ROADMAP.md에는 전체 목표, Phase 개요, Milestone 목록, 로딩 정책을 작성한다.
- agent-ops/roadmap/current.md에는 정해진 current.md 형식 그대로 활성 Milestone 목록과 선택 규칙을 작성한다.
- 각 Milestone 문서에는 아래 섹션을 포함한다.
  - 목표
  - 단계
  - 상태
  - 범위
  - 필수 기능
  - 완료 기준
  - 범위 제외
  - 작업 컨텍스트
- 미래 Milestone은 확정된 내용만 작성하고, 불확실한 기능은 TODO로 둔다.

마일스톤 컨텍스트 로딩 규칙 추가

agent-ops/rules/project/rules.md가 있으면 아래 섹션을 추가한다.

## 마일스톤 컨텍스트 로딩

- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-ops/roadmap/current.md`를 먼저 읽는다.
- `current.md`는 현재 작업 위치가 아니라 활성 Milestone 후보 목록이다.
- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Milestone 문서를 같은 세션에서 1회 읽는다.
- 요청이 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다.
- 활성 Milestone 밖의 작업이면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
- `agent-ops/roadmap/ROADMAP.md`는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다.
- 작업 요청이 선택된 Milestone의 목표 또는 범위 제외 항목과 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다.

같은 섹션이 이미 있으면 중복 추가하지 않고 필요한 문장만 보완한다.
agent-ops/rules/project/rules.md가 없으면 파일을 새로 만들지 말고, 추가하지 못한 항목으로 보고한다.

결과 보고
- 생성한 로드맵 파일 목록
- 활성 Milestone 목록
- rules/project/rules.md에 추가한 로딩 규칙 여부
- 확인이 필요한 TODO 또는 가정

실행 결과 검증

agent-ops/roadmap/ROADMAP.md가 생성되었는가
agent-ops/roadmap/current.md가 활성 Milestone 문서 경로를 정확히 가리키는가
agent-ops/roadmap/milestones/ 하위에 순번 없는 Milestone 문서가 생성되었는가
각 Milestone 문서가 한국어 필수 섹션을 포함하는가
ROADMAP.md에 전체 로드맵을 일반 작업마다 읽지 말라는 로딩 정책이 포함되었는가
agent-ops/rules/project/rules.md가 있는 경우 마일스톤 컨텍스트 로딩 섹션이 추가되었는가
검증 실패 시: 누락된 파일이나 섹션만 보완하고 기존 내용을 덮어쓰지 않는다.

출력 형식

## 생성 완료

- 로드맵: agent-ops/roadmap/ROADMAP.md
- 현재 컨텍스트: agent-ops/roadmap/current.md
- Milestone 문서: <N개>
- 활성 Milestone: <N개>
- 프로젝트 규칙 업데이트: <추가함 | 이미 존재함 | rules/project/rules.md 없음>

## 활성 Milestone

- <milestone-name>: agent-ops/roadmap/milestones/<milestone-slug>.md

## TODO 항목

- <확인이 필요한 가정 또는 미정 항목> (해당 시)

금지 사항

기존 agent-ops/roadmap/ 파일을 덮어쓰지 않는다.
일반 작업마다 전체 ROADMAP.md를 읽도록 규칙을 만들지 않는다.
Phase와 Milestone 이름 또는 파일명에 순번을 강제하지 않는다.
Milestone 문서를 단순 TODO 목록으로만 만들지 않는다. 반드시 목표, 범위, 완료 기준, 범위 제외 항목을 포함한다.
확정되지 않은 제품 방향을 사실처럼 단정하지 않는다.
agent-ops/rules/common/이나 agent-ops/skills/common/을 타겟 프로젝트에서 직접 수정하지 않는다.

9.7 KiB Raw Blame History