sync: agent-ops from agentic-framework v1.1.26

2026-05-21 21:02:03 +09:00 · 2026-05-21 21:02:03 +09:00 · 3d5abeb9d2
commit 3d5abeb9d2
parent 1282c75815
9 changed files with 161 additions and 1 deletions
--- a/.clinerules
+++ b/.clinerules
@ -12,6 +12,7 @@
 - agent-ops 초기화
 - domain rule 생성
 - skill 생성
+- README 생성
 - 로드맵/마일스톤 생성·갱신
 - 현재 작업 지점/남은 작업 분석
 - git commit / push
--- a/.cursorrules
+++ b/.cursorrules
@ -12,6 +12,7 @@
 - agent-ops 초기화
 - domain rule 생성
 - skill 생성
+- README 생성
 - 로드맵/마일스톤 생성·갱신
 - 현재 작업 지점/남은 작업 분석
 - git commit / push
--- a/AGENTS.md
+++ b/AGENTS.md
@ -12,6 +12,7 @@
 - agent-ops 초기화
 - domain rule 생성
 - skill 생성
+- README 생성
 - 로드맵/마일스톤 생성·갱신
 - 현재 작업 지점/남은 작업 분석
 - git commit / push
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -12,6 +12,7 @@
 - agent-ops 초기화
 - domain rule 생성
 - skill 생성
+- README 생성
 - 로드맵/마일스톤 생성·갱신
 - 현재 작업 지점/남은 작업 분석
 - git commit / push
--- a/GEMINI.md
+++ b/GEMINI.md
@ -12,6 +12,7 @@
 - agent-ops 초기화
 - domain rule 생성
 - skill 생성
+- README 생성
 - 로드맵/마일스톤 생성·갱신
 - 현재 작업 지점/남은 작업 분석
 - git commit / push
--- a/agent-ops/.version
+++ b/agent-ops/.version
@ -1 +1 @@
-1.1.25
+1.1.26
--- a/agent-ops/rules/common/rules.md
+++ b/agent-ops/rules/common/rules.md
@ -12,6 +12,7 @@
 - agent-ops 초기화
 - domain rule 생성
 - skill 생성
+- README 생성
 - 로드맵/마일스톤 생성·갱신
 - 현재 작업 지점/남은 작업 분석
 - git commit / push
--- a/agent-ops/skills/common/create-readme/SKILL.md
+++ b/agent-ops/skills/common/create-readme/SKILL.md
@ -0,0 +1,153 @@
+---
+name: create-readme
+version: 1.0.0
+description: README 작성, README 생성, 프로젝트 설명 문서 작성 요청에 대해 사람이 읽기 쉽고 AI가 다음 작업에 바로 활용할 수 있는 표준형 README.md를 생성하는 공통 스킬
+---
+
+# README 생성
+
+## 목적
+
+프로젝트 루트의 `README.md`를 표준형으로 작성한다.
+README는 사람에게 프로젝트의 목적과 사용법을 설명하면서, AI 에이전트가 다음 작업에서 빠르게 맥락을 파악하고 실행할 수 있는 작업 안내 문서가 되도록 구성한다.
+
+## 언제 호출할지
+
+- 사용자가 "README 작성해줘", "README 만들어줘", "프로젝트 설명 문서 만들어줘"라고 요청할 때
+- 프로젝트 루트에 `README.md`가 없거나 내용이 비어 있을 때
+- 기존 README가 제품 설명, 실행 방법, 구조, 검증 명령을 충분히 담지 못해 초기 정리가 필요할 때
+- AI 에이전트가 프로젝트를 이어서 작업할 수 있도록 핵심 맥락을 한 문서에 모아야 할 때
+
+## 입력
+
+- `project-name`: README에 사용할 프로젝트 이름 (선택, 없으면 repo 이름 또는 package metadata에서 추론)
+- `audience`: 주요 독자 또는 사용자 (선택)
+- `purpose`: 프로젝트 목적 한 줄 요약 (선택)
+- `scope`: README에 포함할 범위 또는 제외할 범위 (선택)
+- `overwrite`: 기존 README 덮어쓰기 허용 여부 (선택, 명시 없으면 덮어쓰지 않음)
+
+## README 표준 구성
+
+README는 프로젝트 특성에 맞게 필요한 섹션만 사용하되, 기본 순서는 아래를 따른다.
+
+```markdown
+# <project-name>
+
+<프로젝트 목적 1~3문장>
+
+## 현재 상태
+
+<개발 단계, 사용 가능 범위, 중요한 제약>
+
+## 빠른 시작
+
+<설치, 실행, 테스트의 최소 명령>
+
+## 주요 명령
+
+| 목적 | 명령 | 비고 |
+|------|------|------|
+
+## 구조
+
+| 경로 | 역할 |
+|------|------|
+
+## 작업 맥락
+
+<AI가 다음 작업에서 먼저 알아야 할 규칙, 문서, 로드맵, 주요 경계>
+
+## 개발 흐름
+
+<브랜치, 테스트, 검증, 리뷰 또는 배포 흐름>
+
+## 환경 변수
+
+| 이름 | 설명 | 필수 |
+|------|------|------|
+
+## 참고 문서
+
+- <관련 문서 경로>
+```
+
+## AI-first 작성 기준
+
+- README 상단에는 프로젝트가 무엇을 해결하는지와 현재 사용할 수 있는 범위를 먼저 쓴다.
+- AI가 작업을 이어받을 때 필요한 경로, 명령, 검증 방법, 주요 문서를 명확한 제목과 표로 정리한다.
+- `agent-ops/`가 있으면 규칙, 로드맵, 스킬 문서를 참고 문서나 작업 맥락에 연결한다.
+- `agent-ops/roadmap/current.md`가 있으면 README에 현재 작업 위치를 복사하지 말고, 로드맵을 확인할 문서 경로만 적는다.
+- README는 제품 소개 문서이면서 작업 진입점이다. 마케팅 문구보다 실행 가능한 정보와 프로젝트 경계를 우선한다.
+- 불확실한 내용은 단정하지 않고 `TODO` 또는 "확인 필요"로 남긴다.
+
+## 먼저 확인할 것
+
+- [ ] 루트 `README.md` 존재 여부와 기존 내용 확인
+- [ ] `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Makefile`, `docker-compose.yml` 등 실행/검증 명령 근거 확인
+- [ ] `agent-ops/rules/project/rules.md`가 있으면 프로젝트 개요, 기술 스택, 도메인 매핑 확인
+- [ ] `agent-ops/roadmap/ROADMAP.md` 또는 `agent-ops/roadmap/current.md`가 있으면 제품 방향과 활성 Milestone 문서 경로만 확인
+- [ ] 주요 소스 디렉터리와 테스트 디렉터리를 `rg --files`로 가볍게 확인
+
+## 실행 절차
+
+1. **기존 README 처리 결정**
+   - `README.md`가 없으면 새로 생성한다.
+   - `README.md`가 있고 사용자가 덮어쓰기를 명시하지 않았으면 기존 내용을 보존하고, 필요한 섹션만 보완한다.
+   - 기존 README의 제품 설명, 설치/실행 명령, 경고, 라이선스, 배포 정보를 삭제하지 않는다.
+
+2. **프로젝트 근거 수집**
+   - metadata 파일에서 프로젝트 이름, 설명, scripts, dependencies, runtime을 확인한다.
+   - Makefile, compose 파일, CI 설정, 테스트 설정에서 실행 명령과 검증 명령을 확인한다.
+   - 소스 구조는 전체 정독하지 않고 README 작성에 필요한 상위 경로와 대표 진입점만 확인한다.
+   - 명령을 추론해야 하면 "추정"으로 쓰지 말고 TODO로 남긴다.
+
+3. **README 초안 작성**
+   - 표준 구성 순서를 기준으로 프로젝트에 맞는 섹션을 선택한다.
+   - 빠른 시작에는 최소 실행 경로를 짧게 쓴다.
+   - 주요 명령 표에는 실제로 확인한 명령만 넣는다.
+   - 구조 표에는 AI가 작업 범위를 잡는 데 도움이 되는 경로만 넣는다.
+   - 작업 맥락에는 agent-ops 문서, 로드맵, 도메인 규칙, 중요한 작업 경계를 연결한다.
+
+4. **기존 내용 병합**
+   - 기존 README가 있으면 중복 섹션을 합치고 정보가 더 정확한 쪽을 남긴다.
+   - 확인 근거가 없는 오래된 내용은 삭제하지 말고 "확인 필요"로 표시한다.
+   - 문서의 제목, 명령, 경로 표기가 실제 파일과 맞는지 확인한다.
+
+5. **결과 보고**
+   - 생성 또는 수정한 README 경로
+   - 확인한 실행/테스트 명령
+   - TODO 또는 확인 필요로 남긴 항목
+   - 덮어쓰지 않고 보존한 기존 주요 내용
+
+## 실행 결과 검증
+
+- [ ] 루트 `README.md`가 존재하는가
+- [ ] 프로젝트 목적, 빠른 시작, 주요 명령, 구조, 작업 맥락 중 프로젝트에 필요한 섹션이 포함되어 있는가
+- [ ] README에 적은 명령이 실제 설정 파일 또는 프로젝트 관례에서 확인된 명령인가
+- [ ] README에 적은 경로가 실제로 존재하는가
+- [ ] agent-ops 문서를 복사해 중복하지 않고 필요한 경로만 연결했는가
+- [ ] 불확실한 내용이 단정 표현이 아니라 TODO 또는 확인 필요로 남아 있는가
+- 검증 실패 시: README의 해당 항목만 보완하고, 근거 없는 내용을 새로 만들지 않는다.
+
+## 출력 형식
+
+```markdown
+## README 작성 완료
+
+- README: README.md
+- 처리 방식: <생성 | 보완 | 재작성>
+- 확인한 명령:
+  - <command>
+
+## 확인 필요
+
+- <TODO 또는 확인 필요 항목> (해당 시)
+```
+
+## 금지 사항
+
+- 사용자가 명시하지 않은 상태에서 기존 README를 통째로 덮어쓰지 않는다.
+- 확인하지 않은 설치, 실행, 테스트, 배포 명령을 사실처럼 쓰지 않는다.
+- README를 긴 내부 설계 문서로 만들지 않는다. 상세 규칙은 `agent-ops/` 문서로 연결한다.
+- README에 개인 설정, 비밀값, 로컬 전용 경로를 넣지 않는다.
+- 로드맵이나 도메인 규칙 내용을 README에 길게 복사하지 않는다.
--- a/agent-ops/skills/common/router.md
+++ b/agent-ops/skills/common/router.md
@ -5,6 +5,7 @@
 | agent-ops 세팅해줘, scaffold 만들어줘, 초기화해줘 | `agent-ops/skills/common/init-agent-ops/SKILL.md` |
 | domain rule 만들어줘, rules.md 생성, 새 도메인 규칙 | `agent-ops/skills/common/create-domain-rule/SKILL.md` |
 | skill 만들어줘, SKILL.md 생성, 새 스킬 추가 | `agent-ops/skills/common/create-skill/SKILL.md` |
+| README 작성해줘, README 만들어줘, 프로젝트 설명 문서 만들어줘 | `agent-ops/skills/common/create-readme/SKILL.md` |
 | 로드맵 만들어줘, roadmap 생성, 마일스톤 설계, goal/phase 구조 잡아줘 | `agent-ops/skills/common/create-roadmap/SKILL.md` |
 | 로드맵 업데이트, roadmap 갱신, 마일스톤 갱신, phase 변경, 현재 마일스톤 변경, 로드맵 한국어 전환, 로드맵 번역 | `agent-ops/skills/common/update-roadmap/SKILL.md` |
 | 지금 작업이 뭐지?, 현재 작업 분석, 어디까지 했지?, 남은 작업 뭐야 | `agent-ops/skills/common/analyze-roadmap-position/SKILL.md` |
 @ -1 +1 @@
 .1.25
 .1.26