toki/agentic-framework
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

update documentation and roadmap skill

Browse source
This commit is contained in:
toki 2026-05-22 07:31:15 +09:00
parent 0c64cac95d
commit d107b74953
3 changed files with 52 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -73,7 +73,7 @@ agent-ops/
`Goal`, `Phase`, `Milestone`, `API`, `CLI` 같은 일반 개발 용어와 파일명, 경로, slug 같은 식별자는 영어 또는 숫자를 유지할 수 있습니다.
Phase와 Milestone에는 순번을 강제하지 않습니다. 진행 순서는 `ROADMAP.md`에 적힌 위에서 아래 순서로 봅니다. 새 기능이나 Milestone을 추가할 때는 사용자가 지정한 앞/뒤 위치를 우선하고, 위치 지정이 없으면 Phase 흐름과 의존성을 보고 자동 배치합니다.
Phase와 Milestone에는 순번을 강제하지 않습니다. 진행 순서는 `ROADMAP.md`에 적힌 위에서 아래 순서로 봅니다. 새 작업을 추가할 때는 사용자가 지정한 위치를 우선하고, 단위 지정이 없으면 작업 성격을 보고 새 Milestone, 기존 Milestone의 태스크, 기존 태스크의 하위 작업 중 적절한 단위로 배치합니다.
일반 작업에서는 전체 `ROADMAP.md`를 매번 읽지 않습니다. 먼저 `current.md`의 활성 Milestone 창을 읽고, 요청 범위와 변경 파일에 맞는 Milestone 문서만 읽습니다.

2
agent-ops/GUIDE.md
View file

@ -72,7 +72,7 @@ agent-ops/
로드맵 문서는 사람이 함께 검토하고 수정하는 협업 문서이므로 전체 구성과 설명 문장을 기본 한국어로 작성합니다. Goal, Phase, Milestone, API 같은 일반 개발 용어와 파일명, 경로, slug 같은 식별자는 영어 또는 숫자를 유지할 수 있습니다.
Phase와 Milestone에는 순번을 강제하지 않습니다. 진행 순서는 `ROADMAP.md`에 적힌 위에서 아래 순서로 봅니다. 새 기능이나 Milestone을 추가할 때는 사용자가 지정한 앞/뒤 위치를 우선하고, 위치 지정이 없으면 Phase 흐름과 의존성을 보고 자동 배치합니다.
Phase와 Milestone에는 순번을 강제하지 않습니다. 진행 순서는 `ROADMAP.md`에 적힌 위에서 아래 순서로 봅니다. 새 작업을 추가할 때는 사용자가 지정한 위치를 우선하고, 단위 지정이 없으면 작업 성격을 보고 새 Milestone, 기존 Milestone의 태스크, 기존 태스크의 하위 작업 중 적절한 단위로 배치합니다.
---

72
agent-ops/skills/common/update-roadmap/SKILL.md
View file

@ -1,7 +1,7 @@
---
name: update-roadmap
version: 1.3.0
description: 기존 전체 목표, Phase, 순번 없는 Milestone 기반 한국어 로드맵을 갱신하고 신규 기능/Milestone을 사용자 지정 위치 또는 자동 판단 위치에 배치하며 current.md의 활성 Milestone 창을 동기화하는 공통 스킬
version: 1.4.0
description: 기존 전체 목표, Phase, 순번 없는 Milestone 기반 한국어 로드맵을 갱신하고 신규 작업의 삽입 위치와 단위를 사용자 지정 또는 자동 판단으로 배치하며 current.md의 활성 Milestone 창을 동기화하는 공통 스킬
---
# 로드맵 업데이트
@ -16,7 +16,7 @@ description: 기존 전체 목표, Phase, 순번 없는 Milestone 기반 한국
- 사용자가 "로드맵 업데이트", "마일스톤 갱신", "phase 변경", "현재 활성 마일스톤 바꿔줘"라고 요청할 때
- 사용자가 "로드맵 한국어 전환", "로드맵 번역", "영문 로드맵을 한국어로 바꿔줘"라고 요청할 때
- Milestone 완료, 보류, 폐기, 신규 추가가 필요할 때
- 특정 기능이나 작업을 기존 Milestone 앞/뒤, 특정 Phase 안, 또는 적절한 자동 위치에 추가해야 할 때
- 특정 기능이나 작업을 새 Milestone, 기존 Milestone의 태스크, 기존 태스크 하위 항목 중 적절한 위치에 추가해야 할 때
- 활성 Milestone 창에 포함할 Milestone 목록이 달라졌을 때
- 기본 목표, Phase, Milestone의 목표, 범위, 필수 기능, 완료 기준이 달라졌을 때
- 실제 구현 상태와 로드맵 파일이 어긋난 것 같아 동기화가 필요할 때
@ -27,7 +27,8 @@ description: 기존 전체 목표, Phase, 순번 없는 Milestone 기반 한국
- `target-milestone`: 갱신할 Milestone 이름, slug, 파일 경로 (선택)
- `active-milestones`: 활성 Milestone 창에 둘 Milestone 이름, slug, 파일 경로 목록 (선택)
- `new-feature`: 추가할 기능, 작업, 또는 새 Milestone 설명 (선택)
- `placement`: 새 기능/Milestone 배치 위치. 예: `<anchor-milestone> 앞`, `<anchor-milestone> 뒤`, `<phase-name> 안`, `auto` (선택, 없으면 자동 판단)
- `placement`: 새 작업 배치 위치. 예: `<anchor-milestone> 앞`, `<anchor-milestone> 뒤`, `<milestone-name> 안`, `<phase-name> 안`, `<anchor-task> 앞`, `<anchor-task> 아래`, `auto` (선택, 없으면 자동 판단)
- `placement-unit`: 삽입 단위. `milestone` / `task` / `subtask` / `auto` 중 하나 (선택, 없으면 작업 성격으로 판단)
- `change-summary`: 반영할 방향 변경 또는 진행 상황 요약 (선택)
- `evidence`: 완료 판단에 사용할 파일, PR, 테스트, 커밋, 사용자 설명 (선택)
@ -65,10 +66,29 @@ description: 기존 전체 목표, Phase, 순번 없는 Milestone 기반 한국
- 새 Milestone 파일은 순번 없이 `agent-ops/roadmap/milestones/<milestone-slug>.md`로 만든다.
- 중간에 Phase나 Milestone을 끼워 넣을 수 있도록 기존 항목의 이름과 파일명을 불필요하게 바꾸지 않는다.
- 기존 프로젝트에 이미 순번 파일명이 있으면 대규모 rename을 하지 말고, 갱신 범위에 포함된 새 항목부터 순번 없는 형식을 적용한다.
- 새 기능이나 Milestone은 습관적으로 맨 앞이나 맨 뒤에 붙이지 않는다.
- 사용자가 특정 Milestone 앞/뒤, 특정 Phase 안, 또는 필수 기능 목록 내 위치를 지정하면 목표와 범위 제외 항목에 충돌하지 않는 한 그 위치를 우선한다.
- 사용자가 위치를 지정하지 않으면 `ROADMAP.md`의 Phase 흐름, 기존 Milestone 목표, 선후 의존성, 활성 Milestone 창, 완료 기준을 보고 가장 자연스러운 위치를 자동으로 판단한다.
- 자동 배치한 경우 결과 보고에 선택한 Phase/Milestone과 판단 근거를 짧게 남긴다.
- 새 작업은 습관적으로 새 Milestone으로 만들거나 목록 맨 앞/뒤에 붙이지 않는다.
- 사용자가 특정 Milestone 앞/뒤, 특정 Phase 안, 필수 기능 목록 내 위치, 또는 기존 태스크 앞/뒤/아래를 지정하면 목표와 범위 제외 항목에 충돌하지 않는 한 그 위치를 우선한다.
- 사용자가 위치를 지정하지 않으면 `ROADMAP.md`의 Phase 흐름, 기존 Milestone 목표, 기존 필수 기능/태스크, 선후 의존성, 활성 Milestone 창, 완료 기준을 보고 가장 자연스러운 위치를 자동으로 판단한다.
- 자동 배치한 경우 결과 보고에 선택한 삽입 단위, Phase/Milestone/태스크 위치, 판단 근거를 짧게 남긴다.
## 삽입 단위 정책
신규 추가 요청은 먼저 "어디에 둘지"와 "어떤 단위로 둘지"를 분리해서 판단한다. 여기서 태스크는 Milestone 문서의 `필수 기능`, TODO, 또는 기존 체크리스트 항목을 뜻한다.
| 삽입 단위 | 사용 기준 |
|-----------|-----------|
| 새 Milestone | 독립적인 목표와 완료 기준이 필요하거나, 여러 기능을 묶는 산출물이고, 별도 상태 추적이 필요하며, Phase 흐름이나 선후 의존성에 의미 있는 경계를 만든다 |
| 기존 Milestone의 태스크 | 기존 Milestone의 목표와 범위 안에 들어가며, 하나의 완료 가능한 기능/작업이지만 별도 Milestone 상태 추적까지는 필요하지 않다 |
| 기존 태스크의 하위 작업 | 기존 태스크의 구현 세부, 보완, 테스트, 문서화, 예외 처리, 완료 기준 구체화처럼 부모 태스크를 완성하기 위한 세부 항목이다 |
| 작업 컨텍스트/TODO | 요구가 아직 불확실하거나 조사/확인이 먼저 필요해 필수 기능으로 확정하기 어렵다 |
- 위치 지정이 있으면 anchor의 레벨을 먼저 확인한다. `<anchor-task> 아래`처럼 하위 위치가 명시되면 기존 태스크 하위 항목으로 넣고, `<anchor-task> 앞/뒤`면 같은 목록 레벨의 형제 항목으로 넣는다.
- 위치는 지정됐지만 단위가 명시되지 않은 경우, anchor 레벨과 작업 성격을 함께 보고 새 Milestone, 태스크, 하위 작업 중 하나를 선택한다.
- 위치 지정이 `<phase-name> 안` 또는 `<milestone-name> 안`처럼 컨테이너만 지정된 경우, 작업 내용이 기존 태스크의 세부 구현이면 해당 컨테이너 안에서 가장 관련 있는 태스크 아래에 넣을 수 있다. 이 경우 결과 보고에 "위치는 지정된 컨테이너를 따랐고, 단위는 하위 작업으로 판단"처럼 남긴다.
- 위치 지정이 `<anchor-milestone> 앞/뒤` 또는 `<anchor-task> 앞/뒤`처럼 순서 anchor인 경우, 같은 레벨의 앞/뒤 배치를 유지한다. 작업 성격상 다른 레벨이 더 적절해 보여도 조용히 재배치하지 말고 사용자에게 확인한다.
- `placement-unit`을 사용자가 명시한 경우 그 단위를 우선한다. 다만 지정 단위가 anchor 레벨, Milestone 목표, 범위 제외, 명백한 선후 의존성과 충돌하면 수정 전에 충돌 내용을 알리고 방향을 확인한다.
- 작업이 둘 이상의 Milestone에 걸치면 바로 하나의 기존 태스크에 넣지 않는다. 공통 기반 작업이면 새 Milestone을 고려하고, 단순 연계 작업이면 각 Milestone에 나눌지 사용자에게 확인한다.
- 기존 태스크와 중복되거나 기존 태스크의 완료 기준으로 자연스럽게 흡수되는 요청은 새 Milestone이나 새 형제 태스크로 만들지 말고 기존 태스크를 보완한다.
### current.md 형식
@ -102,25 +122,29 @@ description: 기존 전체 목표, Phase, 순번 없는 Milestone 기반 한국
## 실행 절차
1. **갱신 범위 결정**
- 요청에서 mode, target Milestone, new feature, placement를 추론한다.
- 요청에서 mode, target Milestone, new feature, placement, placement-unit을 추론한다.
- 로드맵 언어 전환 요청이면 `sync`로 보고 `ROADMAP.md`, `current.md`, 전체 Milestone 문서를 갱신 범위에 포함할 수 있다.
- `status` 갱신이면 `current.md`와 대상 Milestone 문서를 우선 읽는다.
- 요청이 활성 Milestone에 없으면 `ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
- Phase 전환, Milestone 추가/삭제, 순서 변경, 전체 재계획이면 `ROADMAP.md`도 읽는다.
- 신규 기능/Milestone 추가이고 placement가 명시되어 있으면 anchor Milestone, 앞/뒤 방향, 대상 Phase를 함께 기록한다.
- 신규 작업 추가이고 placement가 명시되어 있으면 anchor의 종류(Phase, Milestone, 태스크), 앞/뒤/안/아래 방향, 대상 Phase 또는 Milestone을 함께 기록한다.
- 불필요하게 모든 Milestone 문서를 읽지 않는다.
2. **현재 로드맵 상태 파악**
- `ROADMAP.md`의 전체 목표, Phase 개요, Milestone 목록을 확인한다.
- `current.md`의 활성 Milestone 창과 선택 규칙을 확인한다.
- 대상 Milestone 문서의 목표, 범위, 필수 기능, 완료 기준, 범위 제외 항목을 확인한다.
- 대상 또는 후보 Milestone 문서의 목표, 범위, 필수 기능, 완료 기준, 범위 제외 항목을 확인한다.
- 신규 작업과 이름, 산출물, 코드 경계, 완료 기준이 겹치는 기존 태스크가 있는지 확인한다.
3. **신규 기능/Milestone 배치 판단**
- 추가 요청이면 먼저 기존 Milestone의 `필수 기능`에 넣을지, 별도 Milestone으로 분리할지 결정한다.
- 사용자가 위치를 지정한 경우 `ROADMAP.md`에서 anchor Milestone 또는 대상 Phase를 확인하고, 대상 Milestone 문서의 목표와 범위 제외 항목을 읽어 충돌 여부를 확인한다.
3. **신규 작업 삽입 단위와 위치 판단**
- 추가 요청이면 placement, placement-unit, 작업 성격을 함께 보고 새 Milestone, 기존 Milestone의 태스크, 기존 태스크의 하위 작업, 작업 컨텍스트/TODO 중 어느 단위가 맞는지 결정한다.
- 사용자가 위치를 지정한 경우 `ROADMAP.md`에서 anchor Phase/Milestone을 확인하고, 필요한 경우 대상 Milestone 문서의 태스크 anchor까지 확인해 충돌 여부를 확인한다.
- 지정된 anchor가 없거나 여러 항목과 매칭되어 모호하면 임의 배치하지 말고 사용자에게 짧게 확인한다.
- 위치 지정이 없으면 `ROADMAP.md`의 위아래 흐름, 현재 활성 Milestone, 선행되어야 할 작업, 후속 작업이 기대하는 산출물, 관련 코드/문서 경계를 기준으로 자동 배치한다.
- 사용자가 순서 anchor를 지정했으면 같은 레벨의 앞/뒤 배치를 유지하고, 컨테이너 anchor를 지정했으면 컨테이너 안에서 작업 성격에 맞는 하위 단위를 선택한다.
- 위치 지정이 없으면 `ROADMAP.md`의 위아래 흐름, 현재 활성 Milestone, 선행되어야 할 작업, 후속 작업이 기대하는 산출물, 관련 코드/문서 경계, 기존 태스크와의 포함 관계를 기준으로 자동 배치한다.
- 자동 배치는 "가장 빨리 할 수 있는 곳"이 아니라 "의존성과 완료 기준이 자연스럽게 이어지는 곳"을 우선한다.
- 기존 태스크를 완성하는 세부 구현이면 하위 작업으로 넣고, 기존 태스크와 같은 수준의 독립 완료 항목이면 같은 Milestone의 태스크로 넣는다.
- 기존 Milestone의 목표/범위를 넓히거나 완료 기준을 과도하게 키우는 작업이면 새 Milestone으로 분리한다.
- 사용자 지정 위치가 Phase 목표, Milestone 범위 제외, 명백한 선후 의존성과 충돌하면 수정 전에 충돌 내용을 알리고 방향을 확인한다.
4. **변경 내용 검증**
@ -133,7 +157,8 @@ description: 기존 전체 목표, Phase, 순번 없는 Milestone 기반 한국
- `current.md`는 활성 Milestone 창이 바뀔 때 정해진 `current.md 형식`으로 수정한다.
- Milestone 문서는 해당 Milestone의 목표, 범위, 필수 기능, 완료 기준, 범위 제외, 작업 컨텍스트가 바뀔 때 수정한다.
- 새 Milestone은 사용자 지정 또는 자동 판단 위치에 삽입하고, 기존 Milestone 이름이나 파일명을 순서 맞춤 목적으로 바꾸지 않는다.
- 기존 Milestone에 새 필수 기능을 넣는 경우에도 사용자 지정 또는 자동 판단 위치에 삽입하고, 근거 없이 목록 맨 앞이나 맨 뒤에 붙이지 않는다.
- 기존 Milestone에 새 태스크를 넣는 경우에도 사용자 지정 또는 자동 판단 위치에 삽입하고, 근거 없이 목록 맨 앞이나 맨 뒤에 붙이지 않는다.
- 기존 태스크의 하위 작업으로 넣는 경우 기존 문서의 체크박스/불릿 스타일을 유지하고, 부모 태스크의 의미가 바뀌면 부모 문장도 필요한 만큼만 보완한다.
- 상태 값은 `계획`, `진행 중`, `완료`, `보류`, `폐기` 중 하나만 사용한다.
- 완료된 Milestone의 기록은 삭제하지 않고 상태만 변경한다.
@ -146,9 +171,9 @@ description: 기존 전체 목표, Phase, 순번 없는 Milestone 기반 한국
7. **결과 보고**
- 수정한 파일 목록
- 변경된 Phase / Milestone / 상태
- 신규 기능/Milestone 배치 위치와, 자동 배치인 경우 판단 근거
- 신규 작업의 삽입 단위와 배치 위치, 자동 배치인 경우 판단 근거
- 활성 Milestone 창 변경 사항
- 체크하거나 추가/제거한 필수 기능
- 체크하거나 추가/제거한 태스크 또는 하위 작업
- 확인 필요로 남긴 항목
## 실행 결과 검증
@ -156,7 +181,8 @@ description: 기존 전체 목표, Phase, 순번 없는 Milestone 기반 한국
- [ ] `current.md`의 활성 Milestone 경로가 실제 파일을 가리키는가
- [ ] `current.md`가 `# 현재 로드맵 컨텍스트`, `활성 Milestone`, `선택 규칙` 형식을 유지하는가
- [ ] `ROADMAP.md`의 Milestone 목록과 대상 Milestone 문서의 상태가 서로 충돌하지 않는가
- [ ] 신규 기능/Milestone이 사용자 지정 위치를 따랐거나, 위치 미지정 시 자동 배치 근거가 남아 있는가
- [ ] 신규 작업이 사용자 지정 위치를 따랐거나, 위치 미지정 시 자동 배치 근거가 남아 있는가
- [ ] 신규 작업의 삽입 단위가 작업 성격과 기존 태스크 포함 관계에 맞는가
- [ ] 자동 배치 위치가 Phase/Milestone 목표, 범위 제외 항목, 선후 의존성과 충돌하지 않는가
- [ ] 대상 Milestone 문서의 상태가 `계획`, `진행 중`, `완료`, `보류`, `폐기` 중 하나인가
- [ ] 완료 처리한 기능에 사용자 설명 또는 확인 가능한 evidence가 있는가
@ -177,10 +203,11 @@ description: 기존 전체 목표, Phase, 순번 없는 Milestone 기반 한국
## 변경 사항
- Phase: <변경 없음 | 요약>
- 삽입 단위: <Milestone | 태스크 | 하위 작업 | 작업 컨텍스트/TODO | 변경 없음>
- 배치: <사용자 지정 위치 반영 | 자동 배치 위치와 근거 | 변경 없음>
- 활성 Milestone: <변경 없음 | 추가/제거 요약>
- 상태: <변경 없음 | 이전 -> 이후>
- 필수 기능: <추가/수정/완료/제거 요약>
- 태스크: <추가/수정/완료/제거 요약>
## TODO 항목
@ -195,7 +222,8 @@ description: 기존 전체 목표, Phase, 순번 없는 Milestone 기반 한국
- 완료된 Milestone 기록을 삭제하지 않는다.
- Phase와 Milestone 이름 또는 파일명에 순번을 강제하지 않는다.
- 기존 순번 파일명을 대규모 rename하지 않는다.
- 신규 기능이나 Milestone을 근거 없이 항상 맨 앞이나 맨 뒤에 추가하지 않는다.
- 사용자가 지정한 앞/뒤 anchor 또는 대상 Phase를 무시하지 않는다.
- 신규 작업을 근거 없이 항상 새 Milestone으로 만들거나 맨 앞/맨 뒤에 추가하지 않는다.
- 작업 성격과 기존 태스크 포함 관계를 확인하지 않고 모든 신규 작업을 같은 단위로 처리하지 않는다.
- 사용자가 지정한 앞/뒤/아래 anchor 또는 대상 Phase/Milestone 컨테이너를 무시하지 않는다.
- Milestone 목표와 범위 제외 항목을 무시하고 기능 목록만 갱신하지 않는다.
- 타겟 프로젝트에서 `agent-ops/rules/common/` 또는 `agent-ops/skills/common/`을 직접 수정하지 않는다.