상태

저장소 루트에 STATE.md를 유지하십시오: 가벼운 교차 세션 일일 보고서로, 다음 작업자가 약 15줄 내에서 프로젝트의 현재 위치, 마지막 세션에서 수행한 작업, 재사용할 즉각적인 경험, 다음에 수행할 작업, 잊지 말아야 할 미완료 항목을 파악할 수 있습니다. 이것은 개발 경험이 매 세션마다 프로젝트 상태를 재발견하는 대신 축적되도록 하는 피드백 루프입니다.

STATE.md는 일시적("현재 위치 / 다음 작업", 매 세션마다 덮어씀)이며 자체 포함됩니다 — 내구성 있는 결정, 아키텍처 또는 용어집을 위한 장소가 아니며 이를 중복해서는 안 됩니다. 느리게 생성됩니다: 아직 존재하지 않으면 첫 번째 실행이 생성합니다.

프로젝트가 계획 권한(이슈 트래커, 마일스톤)을 유지하는 경우, 해당 권한은 무엇을 할 작업인지 소유합니다. 실행의 순서와 방식을 규정하지 않습니다 — 이슈는 병렬로 실행되고, 하나의 이슈가 여러 세션에 걸쳐 있으며, 삽입된 작업이 계획된 작업을 선점합니다. STATE.md는 실행에 대한 작업자의 보고서입니다: 결과와 추적된 작업의 현재 조정(다음에 시작할 작업, 중단되고 보류된 작업)을 포함합니다. 실행 상태를 기록하며, 두 번째 계획 권한이 되어서는 안 됩니다.

이 기술은 자가 충족적이며 직교적입니다. 프로젝트가 사용하는 다른 것(버전 관리, 이슈/작업 트래커, 설계 문서)과 관계없이 독립적입니다. 그러한 도구가 존재할 수 있다고 가정하지만 특정 도구에 의존하지 않습니다 — 프로젝트가 가진 모든 소스를 읽고 나머지는 건너뜁니다.

간결하게 작성하십시오 — 오해를 유발하기보다는 생략하십시오. 템플릿의 모든 내용 항목은 선택 사항입니다. 업데이트된 날짜는 파일을 다시 작성할 때마다 필수입니다. 내용 줄은 다음 세션에 정확하고 유용한 경우에만 작성하십시오. 값이 누락되었거나, 오래되었거나, 확인되지 않았거나, 명확히 유용하지 않으면 생략하십시오. 잘못된 줄이나 채우기 줄은 없는 것보다 더 나쁩니다. 백로그는 다른 제거 규칙을 사용합니다. 4단계를 따르십시오.

실행 시기

작업 세션 종료 시 / 마무리 시 — 에이전트 런타임이 세션 종료 훅을 통해 이를 알리거나 직접 실행할 수 있습니다.
필요 시, 호스트의 명시적 기술 구문을 사용하여 state 기술을 호출하십시오.

주요 작업자는 세션당 한 번 STATE.md를 업데이트합니다. 병렬 하위 작업 및 하위 에이전트는 업데이트하지 않습니다. 이 규칙은 동시 또는 중복 쓰기를 방지합니다.

무작동 가드: 세션이 실질적인 작업을 수행하지 않은 경우(예: 사소한 Q&A 턴), STATE.md를 변경하지 않고 최대한 날짜만 새로 고치십시오. 비진전 상태로 파일을 계속 변경하지 마십시오.

워크플로우

이 세션이 실제로 완료하거나 변경한 것을 수집하십시오. 주요 출처는 현재 대화입니다. 프로젝트에 지원 도구가 있는 경우 가볍게 확인하십시오(최근 버전 제어 기록, 이슈/작업 트래커) — 선택 사항으로 취급하고 필수는 아닙니다.
현재 단계를 알고 있는 경우에만 거시적 단계를 명시하십시오. 이전 STATE.md의 단계를 기본적으로 전달하지 마십시오 — 변경되었을 수 있거나 이 세션에서 현재 단계를 확인할 수 없는 경우, 오래된 단계를 단언하기보다는 줄을 생략하십시오. (완료된 단계를 현재인 것처럼 작성하는 것은 오해를 유발합니다.) 프로젝트 자체 용어를 사용하십시오.
권장되는 다음 작업을 선택하십시오 — 새로운 세션이 시작해야 할 열린 항목을 실행 순서대로 나열하십시오. 올바른 다음 시작인 경우 여기에 백로그 항목을 승격하십시오.
백로그를 조정하십시오. 미완료 교차 세션 항목에 대해 다음 알고리즘을 적용하십시오:
- 필터링하여 상속. 이전 백로그와 실행되지 않은 "다음 작업" 항목부터 시작하십시오. 항목이 완료되었거나, 사용되지 않았거나, "다음 작업"으로 선택되었거나, 프로젝트 트래커에 기록된 증거가 있는 경우에만 항목을 삭제하십시오. 트래커 참조는 항목에 새 장소가 있다는 증거입니다. 대화를 확인하고 트래커가 있는 경우 확인하십시오. 상태가 불확실한 경우 항목을 유지하십시오.
- 미완료 작업 강등. "다음 작업"으로 선택되지 않은 대체된 작업만 백로그로 이동하십시오. 다음 세션에 재개해야 하는 작업은 "다음 작업"에 속합니다.
- 지연된 작업 보류. 새로 수락된 항목이 다음 세션 이후로 연기되고 다른 장소가 없는 경우 추가하십시오.
- 각 항목에 하나의 장소를 부여하십시오. "다음 작업" 또는 백로그 중 하나에만 넣고 둘 다에 넣지 마십시오.
- 각 백로그 항목에 날짜를 기록하십시오. since YYYY-MM-DD 형식으로 입고 날짜를 기록하십시오.
- 다섯 항목 예산을 적용하십시오. 백로그가 다섯 항목을 초과하거나 항목이 명확히 중요한 경우, 가장 오래된 항목부터 프로젝트 트래커로 이동하십시오. 트래커가 참조를 제공한 후에만 항목을 제거하십시오. 트래커가 없으면 모든 항목을 유지하십시오. 또한 승인된 작성자가 트래커 레코드를 생성할 수 없는 경우 모든 항목을 유지하십시오. 가시적인 오버플로우는 항목에 여전히 내구성 있는 장소가 필요하다는 신호입니다.
"다음 작업"에 도움이 되는 경우에만 경험을 추가하십시오. 이 세션의 작업이 권장되는 다음 작업과 연속적이거나 관련된 경우에만 메모를 포함하십시오. 그래야 메모가 실제로 재사용됩니다. 다음 작업이 관련이 없으면 생략하십시오 — 다음 작업에 도움이 되지 않는 경험은 잡음일 뿐 전쟁 이야기 아카이브가 아닙니다. 프로젝트에 PITFALLS.md가 있는 경우, 내구성 있는 환경, 도구, 권한, 샌드박스 및 도구 호출 지침은 그곳에 보관하십시오. STATE.md는 관련 항목을 가리킬 수 있지만 해당 항목을 복사해서는 안 됩니다.
템플릿에서 STATE.md를 다시 작성하십시오. 파일을 덮어쓰고 추가하지 마십시오. 15줄 이하로 유지하십시오. 4단계의 무손실 규칙이 다섯 개 이상의 백로그 항목을 남기는 경우, 추가 항목당 한 줄을 더 허용하십시오. 줄 제한을 맞추기 위해 항목을 삭제하지 마십시오. 정확하고 유용하지 않은 내용 항목은 생략하십시오. 필터링된 백로그를 새 스냅샷의 일부로 다시 출력하십시오. 업데이트된 날짜를 기록하십시오.
자동 커밋하지 마십시오. 다시 작성된 STATE.md를 작업 트리에 그대로 두십시오. 추적되는지 또는 로컬 전용 작업 보조 도구로 유지되는지는 프로젝트의 선택입니다 — 이 기술은 절대 커밋하지 않습니다.

템플릿

# STATE — <프로젝트>

_교차 세션 일일 보고서(~15줄, `state` 기술을 통해 매 세션마다 다시 작성). 내구성 있는 결정은 다른 곳에 위치합니다._

- **단계/마일스톤:** <현재 단계, 프로젝트 자체 용어로 — 현재 단계를 확인할 수 없으면 생략>
- **마지막 세션:** <완료/변경된 사항; 한 줄, 예: 이슈 #N>
- **경험:** <"다음 작업"에 도움이 되는 일시적 경험 또는 관련 `PITFALLS.md` 항목 링크; 그렇지 않으면 생략>
- **다음 작업:** <다음에 시작할 권장 항목, 실행 순서대로, 예: 이슈 #N>
- **백로그:** <"다음 작업"으로 선택되지 않은 미완료 교차 세션 인계 항목; 항목당 한 줄>
  - <중단되거나 보류된 항목, 트래커 참조(#N)가 있는 경우 연결> _(since YYYY-MM-DD)_
  - <아직 트래커에 없는 항목 — 목록이 넘칠 때 가장 오래된 것부터 승격> _(since YYYY-MM-DD)_

_업데이트: <YYYY-MM-DD>_

(모든 내용 항목은 선택 사항입니다. _업데이트는 파일을 다시 작성할 때마다 필수입니다.)

제약 사항

모든 백로그 변경에 대해 4단계를 따르십시오. 예산을 맞추기 위해 미완료 작업을 삭제하지 마십시오.
다시 작성 및 줄 제한에 대해 6단계를 따르십시오. STATE.md는 현재 스냅샷이지 기록 로그가 아닙니다.
이 세션의 델타만 기록하십시오. 백로그는 필터링된 상태를 앞으로 전달하는 유일한 필드입니다.
파일을 자체 포함된 상태로 유지하십시오. 내구성 있는 결정을 중복하거나 특정 트래커 또는 도구에 의존하지 마십시오.
프로젝트의 확립된 어휘를 사용하십시오.

상태 관리 기술 (State Skill)