From b3b3c07ddb0365360fe4dd66b5ff55c5c0bd8c81 Mon Sep 17 00:00:00 2001 From: toki Date: Thu, 21 May 2026 17:39:28 +0900 Subject: [PATCH] feat: add readme skills and update documentation - Add create-readme skill - Add update-readme skill - Update GUIDE.md - Update common rules - Update router skill --- agent-ops/GUIDE.md | 2 + agent-ops/rules/common/rules.md | 1 + .../skills/common/create-readme/SKILL.md | 139 ++++++++++++++++++ agent-ops/skills/common/router.md | 2 + .../skills/common/update-readme/SKILL.md | 118 +++++++++++++++ 5 files changed, 262 insertions(+) create mode 100644 agent-ops/skills/common/create-readme/SKILL.md create mode 100644 agent-ops/skills/common/update-readme/SKILL.md diff --git a/agent-ops/GUIDE.md b/agent-ops/GUIDE.md index ae9d115..d905b16 100644 --- a/agent-ops/GUIDE.md +++ b/agent-ops/GUIDE.md @@ -63,6 +63,8 @@ agent-ops/ │ ├── create-skill/SKILL.md # 스킬 생성 │ ├── create-roadmap/SKILL.md # Goal/Phase/Milestone 로드맵 생성 │ ├── update-roadmap/SKILL.md # 로드맵 상태/마일스톤 갱신 + │ ├── create-readme/SKILL.md # README 생성 + │ ├── update-readme/SKILL.md # README 정리/갱신 │ └── update-domain-rule/SKILL.md # 도메인 규칙 수정 └── project/ # 프로젝트 스킬 (수정 가능) └── /SKILL.md diff --git a/agent-ops/rules/common/rules.md b/agent-ops/rules/common/rules.md index 36fc7bb..e28ff80 100644 --- a/agent-ops/rules/common/rules.md +++ b/agent-ops/rules/common/rules.md @@ -13,5 +13,6 @@ - domain rule 생성 - skill 생성 - 로드맵/마일스톤 생성·갱신 +- README 생성·갱신 - git commit / push - agent-ops 업데이트 / 진입 파일 재적용 diff --git a/agent-ops/skills/common/create-readme/SKILL.md b/agent-ops/skills/common/create-readme/SKILL.md new file mode 100644 index 0000000..3d1f815 --- /dev/null +++ b/agent-ops/skills/common/create-readme/SKILL.md @@ -0,0 +1,139 @@ +--- +name: create-readme +version: 1.0.0 +description: README.md가 없거나 비어 있는 프로젝트에 사람용 첫 진입점 README를 생성하고, 상세 운영 문서는 GUIDE와 roadmap으로 연결하는 공통 스킬 +--- + +# Create README + +## 목적 + +프로젝트 루트의 `README.md`를 사람용 첫 진입점으로 생성한다. +README는 프로젝트 소개와 문서 허브 역할만 담당하고, 변동이 잦은 로드맵·마일스톤·AI 작업 컨텍스트는 별도 문서로 연결한다. + +## 언제 호출할지 + +- `README.md`가 없거나 거의 비어 있을 때 +- 사용자가 "README 만들어줘", "프로젝트 소개 문서 작성해줘"라고 요청할 때 +- agent-ops 적용 프로젝트의 첫 소개 문서를 표준 구조로 만들 때 +- README에 로드맵 본문을 넣기 전에 문서 역할을 분리해야 할 때 + +## 입력 + +- `project-name`: 프로젝트 이름 (선택, 없으면 디렉터리명/패키지명/기존 문서에서 추론) +- `audience`: README를 읽을 주요 대상 (선택) +- `quick-start-hints`: 설치, 실행, 적용 방법 힌트 (선택) +- `doc-links`: 연결할 상세 문서 목록 (선택) + +## README 역할 + +README는 아래 내용을 짧고 안정적으로 담는다. + +- 이 프로젝트가 무엇인지 +- 왜 필요한지 +- 누구를 위한 것인지 +- 빠르게 어떻게 시작하는지 +- 기본 구조가 어떻게 생겼는지 +- 자세한 문서를 어디서 읽는지 + +README에는 아래 내용을 본문으로 길게 넣지 않는다. + +- 상세 로드맵과 마일스톤 체크리스트 +- 자주 바뀌는 작업 상태와 TODO +- 긴 운영 절차 +- AI가 매 작업마다 읽어야 하는 규칙 전문 +- 내부 의사결정 기록 전문 + +## 권장 구조 + +```markdown +# + +## 개요 + +## 왜 필요한가 + +## 핵심 아이디어 + +## 빠른 시작 + +## 구조 + +## 문서 + +## Roadmap +``` + +`Roadmap` 섹션은 본문을 길게 쓰지 않고 아래처럼 링크 허브로만 둔다. + +```markdown +## Roadmap + +이 프로젝트의 장기 방향과 현재 마일스톤은 `agent-ops/roadmap/`에서 관리한다. + +- 전체 흐름: `agent-ops/roadmap/ROADMAP.md` +- 현재 작업 기준: `agent-ops/roadmap/current.md` +- 마일스톤별 작업 컨텍스트: `agent-ops/roadmap/milestones/` +``` + +## 먼저 확인할 것 + +- [ ] 프로젝트 루트에 `README.md`가 있는지 확인 +- [ ] `README.md`가 이미 충분한 내용을 담고 있으면 덮어쓰지 말고 `update-readme` 사용을 안내 +- [ ] `agent-ops/GUIDE.md`, `agent-ops/roadmap/ROADMAP.md`, `agent-ops/rules/project/rules.md` 존재 여부 확인 +- [ ] 프로젝트 이름과 목적을 확인할 수 있는 manifest, package 파일, 기존 문서를 확인 + +## 실행 절차 + +1. **기존 README 확인** + - `README.md`가 없으면 새로 만든다 + - 비어 있거나 제목만 있으면 부족한 섹션을 채운다 + - 의미 있는 README가 이미 있으면 임의로 교체하지 않고 `update-readme`를 안내한다 + +2. **프로젝트 정보 수집** + - README에 필요한 수준으로만 문서와 상위 구조를 확인한다 + - 전체 코드를 정독하지 않는다 + - 불확실한 기능이나 대상 사용자는 단정하지 않고 짧게 일반화한다 + +3. **README 작성** + - 소개, 문제, 핵심 아이디어, 빠른 시작, 구조, 문서 링크를 간결하게 작성한다 + - 설치/실행 명령은 확인 가능한 경우에만 넣는다 + - `agent-ops/GUIDE.md`가 있으면 상세 적용 가이드로 연결한다 + - `agent-ops/roadmap/ROADMAP.md`가 있으면 Roadmap 섹션에서 링크한다 + - 로드맵 파일이 아직 없으면 "로드맵은 create-roadmap 실행 후 `agent-ops/roadmap/`에서 관리한다" 정도로 짧게 안내한다 + +4. **결과 보고** + - 생성한 README 경로 + - 포함한 주요 섹션 + - 확인하지 못해 생략한 명령이나 링크 + +## 실행 결과 검증 + +- [ ] `README.md`가 생성되었는가 +- [ ] README가 프로젝트 소개와 문서 허브 역할에 집중하는가 +- [ ] 상세 로드맵, 마일스톤 체크리스트, 작업 상태 TODO가 README 본문에 길게 들어가지 않았는가 +- [ ] 존재하는 상세 문서 링크가 실제 파일을 가리키는가 +- [ ] 확인하지 않은 설치/실행 명령을 추측으로 작성하지 않았는가 +- 검증 실패 시: README의 해당 섹션만 보완하고 불확실한 내용은 제거한다 + +## 출력 형식 + +```markdown +## 생성 완료 + +- README: README.md +- 포함 섹션: <섹션 목록> +- 연결 문서: + +## TODO 항목 + +- <확인이 필요한 항목> (해당 시) +``` + +## 금지 사항 + +- 기존의 의미 있는 README를 덮어쓰지 않는다 +- README를 상세 로드맵, 마일스톤, 작업 상태 관리 문서로 사용하지 않는다 +- 확인하지 않은 설치/실행 명령을 추측으로 넣지 않는다 +- agent-ops 내부 규칙이나 스킬 전문을 README에 복사하지 않는다 +- 프로젝트 특화 문서 생성 요청인데 `agent-ops/skills/common/`을 수정하지 않는다 diff --git a/agent-ops/skills/common/router.md b/agent-ops/skills/common/router.md index b3527e3..537f60f 100644 --- a/agent-ops/skills/common/router.md +++ b/agent-ops/skills/common/router.md @@ -7,6 +7,8 @@ | skill 만들어줘, SKILL.md 생성, 새 스킬 추가 | `agent-ops/skills/common/create-skill/SKILL.md` | | 로드맵 만들어줘, roadmap 생성, 마일스톤 설계, goal/phase 구조 잡아줘 | `agent-ops/skills/common/create-roadmap/SKILL.md` | | 로드맵 업데이트, roadmap 갱신, 마일스톤 갱신, phase 변경, 현재 마일스톤 변경 | `agent-ops/skills/common/update-roadmap/SKILL.md` | +| README 만들어줘, README 생성, 프로젝트 소개 문서 작성 | `agent-ops/skills/common/create-readme/SKILL.md` | +| README 정리해줘, README 업데이트, 로드맵 분리해줘, 문서 링크 정리 | `agent-ops/skills/common/update-readme/SKILL.md` | | 계획 세워줘, 구현 계획, PLAN.md, plan | `agent-ops/skills/common/plan/SKILL.md` | | 코드 리뷰해줘, 리뷰 진행해, 리뷰해줘, code review, CODE_REVIEW.md, 리뷰 루프 | `agent-ops/skills/common/code-review/SKILL.md` | | 커밋해줘, 푸시해줘, commit, push, 반영해줘 | `agent-ops/skills/common/commit-push/SKILL.md` | diff --git a/agent-ops/skills/common/update-readme/SKILL.md b/agent-ops/skills/common/update-readme/SKILL.md new file mode 100644 index 0000000..105d165 --- /dev/null +++ b/agent-ops/skills/common/update-readme/SKILL.md @@ -0,0 +1,118 @@ +--- +name: update-readme +version: 1.0.0 +description: 기존 README.md를 프로젝트 첫 진입점과 문서 허브 역할에 맞게 갱신하고, 로드맵·마일스톤·AI 작업 컨텍스트를 별도 문서로 분리하는 공통 스킬 +--- + +# Update README + +## 목적 + +기존 `README.md`를 안정적인 프로젝트 소개 문서로 갱신한다. +README가 상세 로드맵, 마일스톤 체크리스트, 긴 운영 절차를 떠안지 않도록 정리하고, 필요한 상세 문서로 연결한다. + +## 언제 호출할지 + +- 사용자가 "README 정리해줘", "README 업데이트", "로드맵 분리해줘"라고 요청할 때 +- README에 자주 바뀌는 로드맵, TODO, 마일스톤 상태가 섞였을 때 +- agent-ops 구조, roadmap 구조, GUIDE 링크를 README에 반영해야 할 때 +- 프로젝트 구조가 바뀌어 README의 설명이나 문서 링크가 낡았을 때 + +## 입력 + +- `mode`: `refresh` / `split-roadmap` / `link-docs` / `structure` 중 하나 (선택, 요청에서 추론 가능) +- `change-summary`: README에 반영할 변경 요약 (선택) +- `doc-links`: 새로 연결할 상세 문서 목록 (선택) + +## 모드 + +| mode | 사용 상황 | +|------|-----------| +| `refresh` | README의 소개, 구조, 빠른 시작을 현재 상태에 맞게 갱신 | +| `split-roadmap` | README 안의 상세 로드맵/마일스톤을 `agent-ops/roadmap/` 링크로 분리 | +| `link-docs` | GUIDE, roadmap, rules, skills 등 문서 링크 허브 정리 | +| `structure` | README 섹션 순서와 역할을 표준 구조로 재정렬 | + +## README 관리 원칙 + +- README는 프로젝트의 첫 진입점이다 +- README는 사람에게 프로젝트를 이해시키고, 더 자세한 문서로 이동시키는 허브다 +- 변동이 잦은 로드맵 본문은 `agent-ops/roadmap/ROADMAP.md`에서 관리한다 +- 일반 작업에서 AI가 읽는 방향성은 `agent-ops/roadmap/current.md`와 Active Milestone 문서가 담당한다 +- agent-ops 적용 방법의 상세 절차는 `agent-ops/GUIDE.md`가 담당한다 + +## 먼저 확인할 것 + +- [ ] `README.md` 존재 여부 확인 +- [ ] README가 없으면 `create-readme` 스킬 사용을 안내하고 중단 +- [ ] `agent-ops/GUIDE.md` 존재 여부 확인 +- [ ] `agent-ops/roadmap/ROADMAP.md`, `agent-ops/roadmap/current.md`, `agent-ops/roadmap/milestones/` 존재 여부 확인 +- [ ] README 안에 상세 로드맵, TODO, 마일스톤 체크리스트가 있는지 확인 + +## 실행 절차 + +1. **갱신 범위 결정** + - 요청에서 mode를 추론한다 + - README 전체 재작성보다 필요한 섹션만 수정한다 + - README가 심하게 낡았으면 구조 재정렬을 제안하고 진행한다 + +2. **현재 문서 구조 확인** + - README의 현재 섹션과 역할을 파악한다 + - GUIDE, roadmap, rules, skills 등 실제 존재하는 상세 문서만 링크 대상으로 삼는다 + - 설치/실행 명령은 manifest나 기존 문서에서 확인 가능한 경우에만 유지한다 + +3. **README 정리** + - 프로젝트 소개, 문제 정의, 핵심 아이디어, 빠른 시작, 구조, 문서 링크는 README에 유지한다 + - 긴 로드맵 본문은 Roadmap 섹션의 링크 허브로 축약한다 + - 마일스톤 체크리스트와 작업 상태는 README에서 제거하고 `agent-ops/roadmap/` 문서로 이동 또는 이동 필요 TODO로 남긴다 + - agent-ops 내부 규칙 전문은 README에 복사하지 않고 GUIDE/rules/skills로 연결한다 + +4. **Roadmap 섹션 정규화** + - roadmap 구조가 있으면 아래 형식으로 정리한다 + ```markdown + ## Roadmap + + 이 프로젝트의 장기 방향과 현재 마일스톤은 `agent-ops/roadmap/`에서 관리한다. + + - 전체 흐름: `agent-ops/roadmap/ROADMAP.md` + - 현재 작업 기준: `agent-ops/roadmap/current.md` + - 마일스톤별 작업 컨텍스트: `agent-ops/roadmap/milestones/` + ``` + - roadmap 구조가 없으면 create-roadmap 실행 후 분리할 수 있다고 짧게 안내한다 + +5. **결과 보고** + - 수정한 README 섹션 + - 분리하거나 축약한 로드맵/TODO 항목 + - 존재하지 않아 연결하지 않은 문서 + +## 실행 결과 검증 + +- [ ] README가 프로젝트 첫 진입점과 문서 허브 역할에 집중하는가 +- [ ] 상세 로드맵과 마일스톤 체크리스트가 README 본문에서 제거되거나 링크로 축약되었는가 +- [ ] 존재하지 않는 문서 링크를 추가하지 않았는가 +- [ ] 기존 README의 중요한 프로젝트 소개나 사용법을 이유 없이 삭제하지 않았는가 +- [ ] 확인하지 않은 설치/실행 명령을 새로 추가하지 않았는가 +- 검증 실패 시: 잘못 수정한 섹션만 되돌리거나 보완한다 + +## 출력 형식 + +```markdown +## 업데이트 완료 + +- README: README.md +- Mode: +- 수정 섹션: <섹션 목록> +- 연결 문서: + +## TODO 항목 + +- <확인이 필요한 항목> (해당 시) +``` + +## 금지 사항 + +- README가 없는데 새로 만들지 않는다. 이 경우 `create-readme`를 사용한다 +- 기존 README의 중요한 사용법이나 프로젝트 설명을 근거 없이 삭제하지 않는다 +- README를 상세 로드맵, 마일스톤, 작업 상태 관리 문서로 되돌리지 않는다 +- 확인하지 않은 설치/실행 명령이나 기능을 추가하지 않는다 +- agent-ops 내부 규칙이나 스킬 전문을 README에 복사하지 않는다