---
name: code-to-docs
description: 기존 코드와 실행 근거를 읽어 사용자가 선택한 현행 요약, PRD·TRD, Architecture 또는 전체 체계 연결 범위를 문서화한다. 기존 문서도 부분 갱신하며 구현과 루프 실행은 요청 범위에 따른다.
---

# 기존 코드 문서화

## 목적과 입력

코드가 실제로 하는 일과 미확인 의도를 구분해 후속 작업이 믿을 수 있는 문서를 만든다.
요청 범위, 코드·설정·테스트, 기존 문서와 사용자 결정을 입력으로 삼는다.
PRD나 plan/harness/loop가 이미 있어도 필요한 부분을 갱신할 수 있다.

## 범위와 최소 산출물

사용자가 선택한 범위를 따른다. 요청에서 알 수 없으면 선택을 짧게 확인하고 그동안 코드를 조사한다.

| 범위 | 최소 산출물 |
|---|---|
| 현행 요약 | `docs/ARCHITECTURE/overview.md`에 동작·구성·핵심 흐름·실행 방법·한계와 근거 |
| PRD·TRD | `docs/PRD.md`에 관찰된 기능·역할·기준, `docs/TRD.md`에 현재 기술·설정·실행/검증 전제 |
| Architecture | `docs/ARCHITECTURE/overview.md`에 책임·의존·흐름·중요 데이터/API 계약. 영역 파일은 필요할 때만 분리 |
| 전체 체계 연결 | 필요한 위 문서와 `plan_setup/`·`harness_setup/`·`loop_setup/LOOP.md` 연결. 기존 산출물을 재사용 |

IDEA는 필수가 아니다. 요청하면 `docs/IDEA.md`에 코드 사실·사용자가 밝힌 목적·추론한 의도·미확인 가정을 구분한다.
관찰만으로 제품 목표·우선순위가 합의됐다고 쓰지 않는다.

## 진행과 필수 제약

1. 루트 지침과 기존 문서, 진입점·화면/라우트·데이터·인증·실행 설정·테스트를 범위에 맞게 읽는다.
   문서와 코드가 다르면 양쪽 출처를 남긴다. 현재 코드가 사용자 의도를 자동 대체하지 않는다.
2. 문서에 `as-is`와 조사 날짜를 표시하고 주요 주장에 파일/절 또는 실행 근거를 붙인다.
   정적 분석·실제 실행·추론을 구분한다. 코드에 없는 선정 이유·성능·보안 보장을 만들지 않는다.
3. 이상 동작과 없는 검사는 관찰대로 적고 의도 미확인은 OQ 등으로 남긴다.
   현재 동작을 앞으로 반드시 보존할 요구로 승격하지 않는다. 기존 합의와 새 목표는 별도로 표시한다.
4. 실행 관찰은 기존 명령과 격리 데이터를 쓴다. 실데이터 변경·비용·외부 전송은 허용 범위를 확인한다.
   실행 못 한 동작은 확인됐다고 쓰지 않는다. 선택 범위의 문서만 작성하고 근거·링크·흐름을 대조한다.
5. 기존 ID·절 참조·완료 상태·사용자 편집·메모·후미 절을 보존한다. 대체된 요구·TD의 원래 위치에 현재 기준 포인터를 둔다. 루트 지침은 필요한 문서 포인터만 부분 보완한다.
   `in_progress`나 미커밋만으로 중단하지 않고 실제 실행 주체와 파일 충돌을 조사한다.
   공유 상태는 기존 필자가 안전한 경계에서 반영하게 조율하고 사용자 변경과 살아 있는 작업을 보존한다.
6. 전체 연결을 선택했을 때 필요한 `plan-generator` → `harness-setup`·`harness-update` → `loop-setup`·`loop-update` 절차를 이어 수행한다.
   사용자가 해당 단계까지 명시적으로 승인하지 않았으면 단계마다 결과와 다음 스킬을 제안해 승인을 받는다.
   없는 부분만 만들고 이미 구현된 기능을 미구현 태스크로 다시 만들지 않는다.
   현행 고정 phase·모든 기능 테스트·네 검사·Git 초기화/커밋은 문서화의 선행 조건이 아니다. 제품 변경으로 이어지면 아래 Loop 계약을 적용한다.
7. 문서화만 요청하면 문서와 한계 보고로 끝낸다. 구현·테스트 보강·루프 실행도 요청했다면 그 범위를 이어 완료한다.
   승인된 범위에서는 다음 스킬 실행을 사용자에게 떠넘기지 않고 필요한 스킬을 읽거나 호출해 직접 이어 간다.
8. 실행 전 목적·권한·예산의 미결만 해소하고 기존 합의를 재사용한다. Loop 이후 질문·재승인·수동 조치 요청 없이 합의 안에서 복구한다.
   해소 불가 작업/의존은 차단하고 독립 작업 후 증거·변경·재개 지점이 있는 미완료로 종료한다.

현행 화면 관찰과 사용자의 디자인 승인 근거를 구분한다. 문서화만 요청되면 미리보기·승인을 새로 요구하지 않는다.
실제 시각 변경까지 요청되면 디자인 정본의 승인 범위를 확인하고 필요한 PRD 미리보기·사용자 확정을 본격적인 화면 구현·관련 Loop 전에 연결한다.

## 기존 Loop의 제품 변경

현재 요청·유효한 합의·태스크 연결상 기존 Loop의 재개·추가·검증·복구에 속하는 제품 변경은 계약을 계승한다.
LOOP.md의 존재나 과거 완료 이력만으로 새 독립 요청을 편입하지 않는다. 적용 범위와 근거를 기록하고 Loop 작업을 작게 나눠 면제하지 않는다.
`loop_setup/LOOP.md`·STATE와 HARNESS를 읽고 `lint → unit → e2e → task_validation` 판정 순서를 계승한다.
task_validation은 해당 변경 미구현·구현 대화/추론/자체 통과 결론을 비상속한 별도 세션이 맡는다. 앞 실패 뒤 후행 완료 판정을 하지 않는다.
환경 선택(Orca/일반/Others)·충돌/자원 조건·누적 시도와 전체 예산을 보존한다. 같은 방식의 수정은 3회 이내 심층 분석·새 전략으로 전환하며 이력/예산을 초기화하지 않는다.
상세 검증·복구·배정은 `harness-setup`·`harness-update`·`loop-setup`·`loop-update`의 필요한 절차로 이어 수행한다.
새 사용자 지시·계획만·자식 실행 금지가 우선하며 변경된 보장과 미검증을 기록한다. 금지된 실행을 강행하거나 독립 검증 PASS를 꾸미지 않는다.

## 기록과 재개

- 시작·중요한 범위/결정·검증·분석 전환에서 해당 문서 또는 기존 STATE/LOG를 증분 저장한다.
  현재 단계·확정/미결·누적 시도/전략·사용/잔여 예산·다음 행동과 대상 코드/지속 증거를 연결한다.
  새 세션은 이 기록과 실제 코드·미커밋·살아 있는 실행/미반영 결과를 대조해 이어가며 완료·실패 이력을 초기화하지 않는다.
  작은 문서/계획 요청은 해당 문서의 짧은 재개 기록으로 충분하며 전체 계획 체계를 만들지 않는다.

## 완료 증거

선택 범위·변경 문서·관찰 근거·미확인 부분을 보고한다.
문서 생성과 구현/검증 완료를 구분하고 선택 범위 밖 산출물을 완료 조건으로 추가하지 않는다.

## 환경 참고

필요할 때 현재 호스트에 해당하는 참고만 읽는다.
- [Claude Code](references/claude-code.md)
- [Codex](references/codex.md)