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,48 @@
+# Architecture Decision Records
+
+## 철학
+이 템플릿의 핵심 가치는 사용자의 의도를 보존하면서도, 조사와 피드백을 통해 Markdown 문서 품질을 단계적으로 높이는 것이다. 빠르게 초안을 만들되, 근거 없는 최종본을 만들지 않는다.
+
+---
+
+### ADR-001: Markdown-first 문서 산출
+**결정**: 모든 중간 산출물과 최종 산출물은 Markdown으로 작성한다.
+
+**이유**: Markdown은 버전 관리, 리뷰, 재사용, 자동 변환에 적합하고 AI Agent가 구조를 안정적으로 다루기 쉽다.
+
+**트레이드오프**: PDF, DOCX, 슬라이드 같은 최종 배포 형식은 별도 변환 단계가 필요하다.
+
+### ADR-002: PRD를 단일 요구사항 원천으로 사용
+**결정**: `docs/PRD.md`를 문서 목적, 독자, 범위, 톤, 키워드의 기준으로 삼는다.
+
+**이유**: 단계가 길어질수록 AI Agent가 임의로 목표를 확장할 위험이 있다. 단일 원천을 두면 초안과 최종본을 같은 기준으로 평가할 수 있다.
+
+**트레이드오프**: PRD가 빈약하면 후속 산출물도 흐려진다. 필요한 경우 PRD 보강을 먼저 요청해야 한다.
+
+### ADR-003: ResearchNote를 출처 장부로 사용
+**결정**: 웹 조사 결과와 출처 검증은 `docs/ResearchNote.md`에 먼저 정리한 뒤 문서에 반영한다.
+
+**이유**: 최종 문서에서 어떤 주장에 어떤 근거가 사용되었는지 추적할 수 있다.
+
+**트레이드오프**: 짧은 문서라도 조사 단계가 하나 추가된다. 대신 사실 오류와 출처 누락 위험을 줄인다.
+
+### ADR-004: 피드백 지점은 blocked 상태로 표현
+**결정**: 사용자 검토가 필요한 step은 `blocked` 상태와 구체적인 `blocked_reason`을 기록한다.
+
+**이유**: Harness 실행기가 사용자 개입이 필요한 지점을 명확히 멈출 수 있다.
+
+**트레이드오프**: 사용자가 피드백을 작성한 뒤 상태를 `pending`으로 되돌려 재실행해야 한다.
+
+### ADR-005: 초안과 최종본 분리
+**결정**: 초안은 `drafts/`, 최종본은 `final/`에 저장한다.
+
+**이유**: 사용자 검토 흔적과 최종 납품물을 명확히 분리할 수 있다.
+
+**트레이드오프**: 파일 수가 늘어난다. 대신 리뷰와 회귀 확인이 쉬워진다.
+
+### ADR-006: Codex의 AGENTS/Skill/Hook 구조로 이전
+**결정**: Claude 전용 `CLAUDE.md`, `.claude/commands`, `.claude/settings.json` 구조를 Codex의 `AGENTS.md`, `.agents/skills`, `.codex/hooks.json`, `.codex/agents` 구조로 이전한다.
+
+**이유**: Codex는 프로젝트 지침을 `AGENTS.md`로 읽고, 재사용 가능한 워크플로우를 Skill로 관리하며, lifecycle hook과 custom agent를 별도 디렉토리에서 구성한다. 템플릿의 의도를 Codex의 네이티브 구조에 맞추면 실행 맥락과 재사용성이 좋아진다.
+
+**트레이드오프**: Claude Code와의 직접 호환성은 낮아진다. 대신 Codex CLI, Skill, custom agent, hook을 기준으로 한 문서 작성 자동화가 명확해진다.
@@ -0,0 +1,74 @@
+# 문서 작성 하네스 아키텍처
+
+## 디렉토리 구조
+```text
+.
+├── AGENTS.md                 # Codex가 읽는 프로젝트별 문서 작성 규칙
+├── .agents/
+│   └── skills/
+│       ├── document-harness/ # 단계적 문서 작성 Skill
+│       └── document-review/  # 문서 리뷰 Skill
+├── .codex/
+│   ├── config.toml           # Codex 기능, live web search, agent 한도 설정
+│   ├── hooks.json            # Stop/PreToolUse hook 설정
+│   ├── hooks/                # hook 실행 스크립트
+│   └── agents/               # 조사/초안/리뷰 custom agents
+├── docs/
+│   ├── PRD.md                # 사용자 요구사항 원천
+│   ├── ResearchNote.md       # 조사 노트와 출처 장부
+│   ├── DraftFeedback.md      # 초안 피드백
+│   ├── FinalFeedback.md      # 최종 문서 피드백
+│   ├── ARCHITECTURE.md       # 하네스 구조
+│   ├── ADR.md                # 문서 작성 의사결정
+│   └── UI_GUIDE.md           # Markdown 스타일 가이드
+├── drafts/                   # 검토용 초안 산출물
+├── final/                    # 피드백 반영 최종 산출물
+├── phases/                   # Harness task/step 계획과 상태
+└── scripts/
+    ├── execute.py            # codex exec 기반 step 순차 실행기
+    ├── validate_docs.py      # 문서 템플릿 기본 검증
+    └── test_execute.py       # execute.py 안전망 테스트
+```
+
+## 데이터 흐름
+```text
+사용자 입력
+  -> docs/PRD.md
+  -> AGENTS.md 작성 규칙 구체화
+  -> Codex/custom agents 웹 검색 및 출처 검증
+  -> docs/ResearchNote.md
+  -> drafts/ 초안 작성
+  -> docs/DraftFeedback.md 사용자 피드백
+  -> final/ 최종 문서 작성
+  -> docs/FinalFeedback.md 최종 피드백 또는 승인
+```
+
+## Step 설계 패턴
+권장 phase는 아래 순서를 따른다.
+
+1. `rule-synthesis`: `docs/PRD.md`를 읽고 `AGENTS.md`의 문서 작성 규칙을 프로젝트에 맞게 구체화한다.
+2. `research-note`: 웹 검색과 사용자가 제공한 자료를 바탕으로 `docs/ResearchNote.md`를 작성한다. 필요하면 `doc_researcher` agent를 사용한다.
+3. `draft-documents`: `drafts/`에 사용자 검토용 초안을 작성한다.
+4. `draft-feedback-gate`: `docs/DraftFeedback.md`가 비어 있으면 `blocked`로 멈추고 사용자 검토를 요청한다.
+5. `final-documents`: 피드백을 반영해 `final/`에 최종 문서를 작성한다.
+6. `final-feedback-gate`: `docs/FinalFeedback.md`에 승인 또는 추가 수정 요청이 없으면 `blocked`로 멈춘다.
+
+## Codex 구성 책임
+- `AGENTS.md`는 Codex가 매 작업에서 읽는 짧고 지속적인 규칙을 담는다.
+- `.agents/skills/document-harness/`는 phase 생성, research, draft, feedback gate, final 작성 절차를 담는다.
+- `.agents/skills/document-review/`는 변경된 Markdown 문서의 리뷰 체크리스트를 담는다.
+- `.codex/agents/`는 조사, 초안 작성, 리뷰, 근거 점검 역할을 분리한다.
+- `.codex/hooks.json`은 위험 명령 차단과 Stop 시점 문서 검증을 연결한다.
+
+## 상태 관리
+- `pending`: 아직 실행되지 않은 step.
+- `completed`: step 산출물이 생성되었고 검증이 끝난 상태.
+- `blocked`: 사용자 피드백, 자료 제공, 승인 등 외부 입력이 필요한 상태.
+- `error`: 자동 수정 3회 후에도 실패한 상태.
+
+## 파일 책임
+- `docs/PRD.md`는 사용자의 의도와 요구사항을 보존한다. Codex가 임의로 요구사항을 바꾸지 않는다.
+- `docs/ResearchNote.md`는 사실 검증의 근거 장부다. 최종 문서의 외부 주장은 이 파일의 출처와 연결되어야 한다.
+- `drafts/`는 논의용이다. 문장이 거칠 수 있지만 구조와 근거는 검토 가능해야 한다.
+- `final/`은 납품용이다. 사용자 피드백, 출처, 스타일 기준을 반영해야 한다.
+- `phases/`의 `index.json`과 `stepN.md`는 독립 실행 가능한 작업 지시서다.
@@ -0,0 +1,23 @@
+# Draft Feedback
+
+초안 검토 후 사용자가 피드백을 남기는 파일이다. AI Agent는 이 파일을 읽고 `final/` 문서에 반영한다.
+
+## 검토 대상
+- `drafts/{파일명}`
+
+## 전체 판단
+- {예: 방향 승인 / 구조 수정 필요 / 추가 조사 필요 / 톤 변경 필요}
+
+## 수정 요청
+| 위치 | 요청 | 이유 |
+|------|------|------|
+| {섹션 또는 파일명} | {수정 요청} | {왜 필요한지} |
+
+## 추가로 포함할 내용
+- {추가 내용}
+
+## 제외하거나 줄일 내용
+- {삭제/축소할 내용}
+
+## 승인 여부
+{예: 초안 방향 승인 / 아직 승인하지 않음}
@@ -0,0 +1,17 @@
+# Final Feedback
+
+최종 문서 검토 후 사용자가 승인 또는 추가 수정 요청을 남기는 파일이다.
+
+## 검토 대상
+- `final/{파일명}`
+
+## 승인 여부
+{예: 승인 / 수정 후 승인 / 승인하지 않음}
+
+## 최종 수정 요청
+| 위치 | 요청 | 우선순위 |
+|------|------|----------|
+| {섹션 또는 파일명} | {수정 요청} | {높음/중간/낮음} |
+
+## 비고
+- {추가 의견}
@@ -0,0 +1,68 @@
+# PRD: {문서 프로젝트명}
+
+이 파일은 Codex 문서 작성 Harness의 출발점이다. 사용자는 아래 항목을 가능한 한 구체적으로 채운다. Codex는 이 문서를 기준으로 작성 규칙, 조사 계획, 초안, 최종 문서를 만든다.
+
+## 문서 목적
+{이 문서가 해결하려는 문제, 설득하려는 주장, 설명하려는 주제, 또는 독자가 얻어야 할 결과를 한 문단으로 작성}
+
+## 대상 독자
+- 주요 독자: {예: 경영진, 개발자, 학생, 고객, 정책 담당자}
+- 독자의 배경지식: {초급/중급/전문가, 알고 있다고 가정해도 되는 것}
+- 독자가 문서를 읽은 뒤 해야 할 행동: {결정, 학습, 실행, 검토, 공유 등}
+
+## 최종 산출물
+| 문서명 | 목적 | 예상 분량 | 필수 포함 요소 |
+|--------|------|-----------|----------------|
+| {예: executive-summary.md} | {요약/설득/보고} | {예: 2쪽} | {핵심 메시지, 근거, 권고안} |
+| {예: full-report.md} | {상세 설명} | {예: 10쪽} | {배경, 분석, 결론, 참고문헌} |
+
+## 문서 개요
+{원하는 목차, 포함해야 할 흐름, 반드시 다뤄야 할 섹션을 작성}
+
+## 중요 키워드
+- {키워드 1}
+- {키워드 2}
+- {키워드 3}
+
+## 핵심 질문
+- {문서가 반드시 답해야 하는 질문 1}
+- {문서가 반드시 답해야 하는 질문 2}
+- {문서가 반드시 답해야 하는 질문 3}
+
+## 범위
+### 포함할 것
+- {포함 범위 1}
+- {포함 범위 2}
+
+### 제외할 것
+- {제외 범위 1}
+- {제외 범위 2}
+
+## 톤과 스타일
+- 톤: {예: 전문적, 차분한 보고서, 친근한 설명문, 강한 설득형}
+- 언어: {예: 한국어, 영어, 한영 병기}
+- 문체: {예: 간결한 문장, 긴 분석형 문단, bullet 중심}
+- 금지 표현: {예: 과장 광고 문구, "혁신적인", "압도적인" 같은 근거 없는 표현}
+
+## 참고 자료
+사용자가 이미 가진 자료나 반드시 참고해야 할 링크를 적는다.
+
+| 제목 | URL 또는 파일 경로 | 참고 이유 |
+|------|-------------------|-----------|
+| {자료명} | {URL/path} | {왜 중요한지} |
+
+## 조사 요구사항
+- 검색해야 할 주제: {예: 시장 규모, 기술 동향, 경쟁 사례, 법적 요건}
+- 선호 출처: {예: 공식 문서, 학술 논문, 정부/기관 자료, 기업 보고서}
+- 피해야 할 출처: {예: 출처 불명 블로그, 홍보성 기사}
+- 최신성 기준: {예: 최근 2년, 2025년 이후, 최신 버전}
+
+## 품질 기준
+- {예: 모든 핵심 주장에 출처를 달 것}
+- {예: 결론 전에 대안과 반론을 함께 검토할 것}
+- {예: 초안은 빠르게, 최종본은 문장 품질과 일관성을 엄격히 볼 것}
+
+## 사용자 피드백 방식
+- 초안 피드백 위치: `docs/DraftFeedback.md`
+- 최종 피드백 위치: `docs/FinalFeedback.md`
+- 승인 기준: {예: 사용자가 명시적으로 "승인"이라고 남기면 완료}
@@ -0,0 +1,54 @@
+# Research Note: {문서 프로젝트명}
+
+이 파일은 조사 내용과 출처를 보존하는 장부다. 최종 문서에 들어가는 외부 사실, 통계, 인용, 사례는 가능한 한 이 파일의 항목과 연결되어야 한다.
+
+## 조사 범위
+- 기준 PRD: `docs/PRD.md`
+- 조사 주제: {조사할 주제}
+- 제외 주제: {조사하지 않을 주제}
+- 최신성 기준: {예: 최근 2년, 2025년 이후, 최신 공식 문서}
+
+## 조사 일시
+- 시작: {YYYY-MM-DD HH:mm, timezone}
+- 종료: {YYYY-MM-DD HH:mm, timezone}
+- 조사자: AI Agent
+
+## 검색어
+| 검색어 | 목적 | 결과 메모 |
+|--------|------|-----------|
+| {검색어} | {무엇을 확인하려 했는지} | {핵심 결과} |
+
+## 핵심 결론
+1. {조사에서 확인한 핵심 결론}
+2. {조사에서 확인한 핵심 결론}
+3. {조사에서 확인한 핵심 결론}
+
+## 출처 목록
+| ID | 제목 | URL | 게시일/확인일 | 신뢰도 | 관련 키워드 |
+|----|------|-----|---------------|--------|-------------|
+| S1 | {출처 제목} | {URL} | {날짜} | {공식/학술/언론/블로그 등} | {키워드} |
+
+## 출처별 메모
+### S1: {출처 제목}
+- URL: {URL}
+- 요지: {핵심 내용 요약}
+- 문서에 쓸 수 있는 내용: {반영할 사실/사례/근거}
+- 주의사항: {한계, 편향, 오래된 정보, 상충 자료}
+
+## 키워드별 정리
+### {키워드}
+- 확인된 사실: {내용}
+- 관련 출처: {S1, S2}
+- 문서 반영 위치: {draft/final의 예상 섹션}
+
+## 쟁점과 상반된 주장
+| 쟁점 | 주장 A | 주장 B | 판단/처리 |
+|------|--------|--------|-----------|
+| {쟁점} | {내용과 출처} | {내용과 출처} | {문서에서 어떻게 다룰지} |
+
+## 확인 필요
+- {추가 확인이 필요한 사실}
+- {사용자에게 물어봐야 할 내용}
+
+## 문서 반영 메모
+- {어떤 결론을 어떤 문서/섹션에 반영할지}
@@ -0,0 +1,54 @@
+# Markdown 문서 스타일 가이드
+
+## 원칙
+1. 독자의 다음 행동이 분명해야 한다. 설명문이라면 이해, 보고서라면 판단, 가이드라면 실행이 가능해야 한다.
+2. 근거와 의견을 섞지 않는다. 사실, 해석, 권고를 구분해 쓴다.
+3. AI가 쓴 듯한 일반론보다 사용자의 목적과 키워드에 맞춘 구체성을 우선한다.
+
+## AI 문서 안티패턴
+| 금지 사항 | 이유 |
+|-----------|------|
+| "오늘날 빠르게 변화하는 시대에" 같은 상투적 도입 | 정보 밀도가 낮고 AI 생성문처럼 보인다 |
+| 근거 없는 최상급 표현 | 신뢰를 떨어뜨린다 |
+| 출처 없는 통계와 수치 | 검증할 수 없다 |
+| 같은 의미의 문장을 반복해 분량 늘리기 | 독자의 시간을 낭비한다 |
+| 목차와 본문 제목 불일치 | 리뷰와 유지보수가 어려워진다 |
+| PRD에 없는 독자나 목표 추가 | 사용자 의도를 벗어난다 |
+| ResearchNote에 없는 외부 주장 단정 | 출처 추적이 끊긴다 |
+| AGENTS.md와 Skill 지침 불일치 | Codex 실행 맥락이 흔들린다 |
+
+## 구조
+- 문서 제목은 `#` 하나만 사용한다.
+- 주요 섹션은 `##`, 하위 섹션은 `###`를 사용한다.
+- 한 섹션에는 하나의 중심 메시지만 둔다.
+- 긴 목록은 표로 바꿀 수 있는지 검토한다.
+- 결론 문서라면 "요약 -> 근거 -> 판단/권고 -> 한계" 순서를 우선 고려한다.
+- 설명 문서라면 "맥락 -> 핵심 개념 -> 절차/예시 -> 주의사항" 순서를 우선 고려한다.
+
+## 문체
+- 문장은 가능한 한 짧게 쓴다.
+- 모호한 주어를 피한다.
+- "중요하다", "효과적이다"처럼 평가를 쓸 때는 이유나 근거를 바로 붙인다.
+- 불확실한 정보는 확률적 표현 또는 확인 필요 표시를 사용한다.
+- 한국어 문서에서는 불필요한 영어 약어를 피하고, 처음 등장할 때 풀어쓴다.
+
+## 출처 표기
+- 외부 사실은 문장 끝이나 문단 끝에 출처 링크를 붙인다.
+- 긴 직접 인용보다 요약과 해석을 우선한다.
+- 같은 출처를 반복해서 사용할 때도 어떤 주장에 연결되는지 분명히 한다.
+- 출처가 상충하면 `docs/ResearchNote.md`의 "쟁점/상반된 주장"에 기록한다.
+
+## 표와 목록
+- 비교, 분류, 의사결정 기준은 표를 우선 검토한다.
+- 순서가 중요한 절차는 번호 목록을 사용한다.
+- 단순 나열은 bullet을 사용한다.
+- 표는 너무 넓어지면 섹션을 나누거나 요약 표와 상세 설명을 분리한다.
+
+## 최종 점검
+- PRD의 목적과 대상 독자에 맞는가?
+- 모든 핵심 질문에 답했는가?
+- 외부 주장에 출처가 있는가?
+- 초안 피드백이 반영되었는가?
+- 문서 제목, 섹션 제목, 파일명이 산출물 목적과 맞는가?
+- 최종 문서는 `final/` 아래에 있는가?
+- Codex Skill, agent, hook 지침과 충돌하지 않는가?