modify documents

2026-04-28 01:30:16 +09:00
parent 246d164827
commit 949e0ab13c
137 changed files with 5172 additions and 1154 deletions
@@ -0,0 +1,131 @@
+---
+name: "document-harness"
+description: "Use when creating, running, or updating the staged Markdown document-writing Harness from docs/PRD.md through research notes, drafts, feedback gates, and final documents."
+---
+
+# Document Harness Skill
+
+Use this skill to turn `docs/PRD.md` into researched, reviewable, and feedback-driven Markdown documents.
+
+## Operating Rules
+
+1. Read `AGENTS.md`, `docs/PRD.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`, and `docs/UI_GUIDE.md` before planning document work.
+2. Treat `docs/PRD.md` as the single source of requirements.
+3. If PRD purpose, target reader, final deliverables, scope, or key questions are materially empty, stop and ask the user to complete PRD first.
+4. Use `docs/ResearchNote.md` as the evidence ledger before drafting externally factual content.
+5. Store review drafts under `drafts/` and final deliverables under `final/`.
+6. Preserve `docs/DraftFeedback.md` and `docs/FinalFeedback.md`; never delete user feedback.
+7. Run `python scripts/validate_docs.py` before reporting completion.
+
+## Staged Workflow
+
+### 1. PRD Intake
+
+Read `docs/PRD.md` and identify:
+
+- document purpose
+- target readers
+- final deliverables
+- required outline
+- important keywords
+- key questions
+- scope boundaries
+- tone and style constraints
+- research requirements
+
+### 2. Rule Synthesis
+
+Update only the relevant project-specific guidance in `AGENTS.md`.
+
+Include:
+
+- document purpose and target readers
+- final deliverables
+- tone and style rules
+- citation and verification standards
+- draft and final feedback process
+
+Keep the generic Codex configuration and repository workflow concise.
+
+### 3. Research Note
+
+Research PRD keywords and key questions. Prefer official, academic, government, institutional, or other primary sources.
+
+Write `docs/ResearchNote.md` with:
+
+- search date
+- search terms
+- source URLs
+- source quality notes
+- core findings
+- conflicting claims
+- unresolved questions
+- intended document usage
+
+Use `doc_researcher` or `evidence_checker` agents when the user or current phase explicitly asks for subagent work.
+
+### 4. Draft Documents
+
+Create all PRD deliverables under `drafts/`.
+
+Drafts must:
+
+- answer the PRD key questions
+- stay inside PRD scope
+- use the requested tone
+- link factual claims to `docs/ResearchNote.md`
+- mark weak or missing evidence
+
+After drafting, request user review in `docs/DraftFeedback.md`.
+
+### 5. Draft Feedback Gate
+
+If `docs/DraftFeedback.md` has no actionable user feedback or approval, mark the phase step as `blocked` with a clear `blocked_reason`.
+
+If feedback exists, summarize it before revising.
+
+### 6. Final Documents
+
+Create final deliverables under `final/`. Do not overwrite `drafts/`.
+
+Final documents must reflect:
+
+- PRD requirements
+- ResearchNote evidence
+- DraftFeedback requests
+- UI guide style rules
+
+After finalizing, request user review or approval in `docs/FinalFeedback.md`.
+
+### 7. Final Feedback Gate
+
+If `docs/FinalFeedback.md` does not contain approval or actionable next feedback, mark the phase step as `blocked`.
+
+If approval exists, mark the phase completed.
+
+## Phase Files
+
+When creating a new phase, use `references/phase-templates.md`.
+
+Each step must include:
+
+- files to read
+- exact task
+- acceptance criteria
+- validation procedure
+- status update instructions
+- concrete forbidden actions
+
+## Validation
+
+Always run:
+
+```bash
+python scripts/validate_docs.py
+```
+
+For executor changes, also run:
+
+```bash
+python -m pytest scripts/test_execute.py
+```
@@ -0,0 +1,85 @@
+# Document Harness Phase Templates
+
+## Top-Level Phase Index
+
+Create or update `phases/index.json`.
+
+```json
+{
+  "phases": [
+    {
+      "dir": "0-document",
+      "status": "pending"
+    }
+  ]
+}
+```
+
+## Task Index
+
+Create `phases/{task-name}/index.json`.
+
+```json
+{
+  "project": "<문서 프로젝트명>",
+  "phase": "<task-name>",
+  "steps": [
+    { "step": 0, "name": "rule-synthesis", "status": "pending" },
+    { "step": 1, "name": "research-note", "status": "pending" },
+    { "step": 2, "name": "draft-documents", "status": "pending" },
+    { "step": 3, "name": "draft-feedback-gate", "status": "pending" },
+    { "step": 4, "name": "final-documents", "status": "pending" },
+    { "step": 5, "name": "final-feedback-gate", "status": "pending" }
+  ]
+}
+```
+
+## Step File
+
+Create `phases/{task-name}/step{N}.md`.
+
+```markdown
+# Step {N}: {이름}
+
+## 읽어야 할 파일
+
+먼저 아래 파일들을 읽고 문서 목적과 작성 기준을 파악하라:
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/UI_GUIDE.md`
+- {이전 step에서 생성/수정된 파일 경로}
+
+## 작업
+
+{구체적인 문서 작성 또는 검토 지시. 파일 경로, 산출물 이름, 반영해야 할 PRD 항목, 출처 기준을 포함한다.}
+
+## Acceptance Criteria
+
+```bash
+python scripts/validate_docs.py
+```
+
+## 검증 절차
+
+1. 위 AC 커맨드를 실행한다.
+2. 문서 체크리스트를 확인한다:
+   - `docs/PRD.md`의 목적, 독자, 범위를 벗어나지 않았는가?
+   - 외부 사실은 `docs/ResearchNote.md`의 출처와 연결되는가?
+   - 초안은 `drafts/`, 최종본은 `final/`에 분리되었는가?
+   - 사용자 피드백 파일을 삭제하거나 덮어쓰지 않았는가?
+3. 결과에 따라 `phases/{task-name}/index.json`의 해당 step을 업데이트한다:
+   - 성공 -> `"status": "completed"`, `"summary": "산출물 한 줄 요약"`
+   - 수정 3회 시도 후에도 실패 -> `"status": "error"`, `"error_message": "구체적 에러 내용"`
+   - 사용자 개입 필요 -> `"status": "blocked"`, `"blocked_reason": "구체적 요청 사항"` 후 즉시 중단
+
+## 금지사항
+
+- PRD에 없는 문서 목표를 추가하지 마라. 이유: 사용자 의도가 흐려진다.
+- 출처 없는 외부 사실을 최종 문서에 단정하지 마라. 이유: 검증 가능성이 사라진다.
+- 초안 파일을 최종본으로 덮어쓰지 마라. 이유: 피드백 전후 변경 추적이 어렵다.
+- 사용자 피드백 파일을 삭제하지 마라. 이유: 의사결정 기록이 사라진다.
+- 직접 `git commit`하지 마라. 이유: `scripts/execute.py`가 step 완료 후 커밋을 관리한다.
+```
@@ -0,0 +1,45 @@
+---
+name: "document-review"
+description: "Use when reviewing Markdown document changes for PRD alignment, source traceability, feedback coverage, structure, and final delivery readiness."
+---
+
+# Document Review Skill
+
+Use this skill to review changed Markdown files in the Codex Markdown Document Harness.
+
+## Read First
+
+- `AGENTS.md`
+- `docs/PRD.md`
+- `docs/ResearchNote.md`
+- `docs/DraftFeedback.md`
+- `docs/FinalFeedback.md`
+- `docs/ARCHITECTURE.md`
+- `docs/ADR.md`
+- `docs/UI_GUIDE.md`
+
+## Review Checklist
+
+1. PRD alignment: purpose, target reader, deliverables, scope, and tone match `docs/PRD.md`.
+2. Source traceability: external facts, dates, statistics, claims, and quotations connect to `docs/ResearchNote.md`.
+3. Structure: heading hierarchy, section order, and file names match the intended deliverables.
+4. Feedback coverage: `docs/DraftFeedback.md` or `docs/FinalFeedback.md` requests are addressed.
+5. Draft/final separation: drafts live under `drafts/`; final deliverables live under `final/`.
+6. Style quality: avoid generic AI prose, unsupported superlatives, repetition, and vague claims.
+7. Validation: `python scripts/validate_docs.py` passes.
+
+## Output Format
+
+Lead with findings. Use this table when a full checklist result is useful:
+
+| 항목 | 결과 | 비고 |
+|------|------|------|
+| PRD 정합성 | PASS/FAIL | {상세} |
+| 출처 추적 | PASS/FAIL | {상세} |
+| 문서 구조 | PASS/FAIL | {상세} |
+| 피드백 반영 | PASS/FAIL | {상세} |
+| 초안/최종본 분리 | PASS/FAIL | {상세} |
+| 문체 품질 | PASS/FAIL | {상세} |
+| 검증 가능성 | PASS/FAIL | {상세} |
+
+If there are issues, include concrete file paths and suggested fixes.