결정 노트
사용자 거절, 실패한 시도, 비교 후 선택되지 않은 옵션, 연기된 항목, 범위 밖 항목을 명확히 구분하세요. 이 모든 것을 영구적으로 불가능한 것으로 취급하지 마세요.
노트는 미해결 제안, 완전한 요구사항, 구현 단계, 작업 진행 상황 또는 문제 해결 로그를 위한 것이 아닙니다. 제안과 구현 계획은 설계 및 계획 문서에 유지하고, 현재 동작은 해당 서브시스템 문서에서 유지하며 소스 코드와 대조하여 확인하세요. 장기적인 근거는 노트에 유지하고, 다른 곳에서 요약하여 링크하세요.
1. 결정 및 변경 전 검색
다음 작업을 시작하기 전에 적용 가능한 프로젝트 수준 제약 조건, 관련 서브시스템 문서 및 관련 노트를 참조하세요:
- 구체적인 솔루션 제안, 동작 결정 또는 주요 설계 트레이드오프 수행.
- 관련 구현 또는 동작 테스트 변경; 서브시스템 간 작업의 경우 관련 인터페이스 및 공유 제약 조건을 포함.
- 결정 기록 생성 또는 변경; 먼저 동일한 주제에 대한 기존 결론을 검색.
사용자가 기록에 대해 질문하거나, 결정 포인터가 발견되거나, 충돌이 발생하면 관련 기록을 직접 읽으세요. 순수한 철자, 형식 및 상태 업데이트는 설정된 제약 조건을 포함하지 않는 경우 새 검색이 필요하지 않습니다.
다음 순서로 기록을 찾고 평가하세요:
- 프로젝트의 에이전트 진입점을 사용하여 실제 노트 위치와 적용 가능한 전역 제약 조건을 찾으세요. 서브시스템 문서를 사용하여 현재 책임, 계약, 소스 코드, 테스트 및 관련 노트를 찾으세요. 서브시스템은 패키지나 저장소에 걸쳐 있을 수 있으며, 하나의 노트가 여러 서브시스템과 관련될 수 있습니다.
- 링크를 따라간 다음, 필요에 따라 질문, 메커니즘, 솔루션 이름 및 제약 조건으로 검색하세요. 링크, 해당 코드 또는 일치하는 이름이 없다고 해서 관련 기록이 없다는 증거는 아닙니다. 서브시스템 페이지가 없으면 사용 가능한 자료와 작업 주제에서 관련 컨텍스트를 찾고, 미리 빈 문서를 만들지 마세요.
- 제목,
상태,범위및 결론부터 시작하고, 관련이 있을 때 근거, 대안 및 증거를 읽으세요. 현재 유효한 기록을 선호하고, 관련성에 따라 기록을 추적하세요. 오래된 옵션을 재고하거나 현재 지침이 불충분할 때는 보관된 기록을 직접 검색하세요. 문제의 범위에 따라 대체를 추적하고, 임의의 체인을 끝까지 따르지 마세요. - 기록의 적용 가능성과 현재 사실을 확인하세요. 디렉토리가 실제로 존재하지 않으면 계속 진행하고, 기록이 처음 필요할 때만 생성하세요. 읽기 실패 또는 검색 결과 없음이 기록이 없다는 증거는 아닙니다.
동일한 작업 내에서 이미 확인되었고 여전히 적용 가능한 결과를 재사용하세요. 범위, 핵심 전제 또는 관련 기록이 변경되거나 충돌이 발생하면 영향을 받는 부분을 다시 확인하세요. 턴이나 스킬이 변경되었다고 해서 모든 것을 다시 스캔하지 마세요.
이전 옵션의 전제가 명확하게 변경된 경우에만 적극적으로 다시 제기하고, 이전에 선택되지 않은 이유, 변경된 조건 및 영향을 설명하세요. 사용자가 이전 결정을 명시적으로 변경하면 승인을 다시 요청하지 않고 새 지침을 따르세요. 일반적인 구현 승인이 기존 거부 또는 범위 제한을 자동으로 취소하지는 않습니다.
2. 기록 생성 여부 결정
새 기록은 다음 모든 조건을 충족해야 합니다:
- 결론이 확정되었습니다. 채택, 거부, 연기 또는 범위 제한이 있거나, 실패 결과와 장기적으로 보존할 가치가 있는 조건이 있습니다. 해결되지 않은 제안과 검증을 기다리는 가정은 설계 문서와 계획에 속합니다.
- 지속적인 가치가 있습니다. 근거가 없으면 미래 에이전트가 오래된 옵션을 다시 제기하거나, 의미 있는 실패 시도를 반복하거나, 중요한 제약 조건을 실수로 변경할 수 있습니다. 단순히 현재 동작을 다시 설명하는 것은 이 임계값을 충족하지 못합니다.
- 별도의 기록이 필요합니다. 관련 기록을 검색했으며, 사실 업데이트, 증거 추가 또는 범위 명확화로 정보를 포착할 수 없습니다. 진정한 결정 변경은 대체 규칙에 따라 새 기록이 필요합니다. 날짜, 전달 횟수 또는 대안 수에 따라 기계적으로 기록을 생성하지 마세요.
일반적인 주제에는 명확하지 않은 서브시스템 경계, 인터페이스 또는 지속성 및 호환성 선택; 중요한 선택과 대안을 선택하지 않은 이유; 캐싱 또는 자동 재시도를 의도적으로 피한 이유; 다시 제기될 수 있는 중요한 거부 또는 연기; 및 증거 기반의 장기적인 실패 결론 또는 교차 작업 정책이 포함됩니다.
일반적으로 형식, 기계적 이름 변경, 코드와 테스트로 이해할 수 있는 일반적인 구현 또는 수정, 일상적인 종속성 업그레이드, 일반적인 문제 해결 시도, 로그, TODO 또는 진행 상황에 대한 노트를 생성하지 마세요. 크기는 기준이 아닙니다. 작업으로 인해 기존 노트가 부정확해지면 유지하고, 임계값을 충족하는 결정이 생성되면 새 결정을 기록하세요.
보존할 명확한 장기적 가치가 없으면 템플릿을 채우기 위해 기록을 생성하지 마세요. 사용자가 중요한 결정을 보존하도록 명시적으로 요청하면 적절한 소스를 재사용하거나 생성하고, 조용히 폐기하지 마세요.
3. 실제 결론을 신속하게 기록
중요한 결론이 명확해지면 완료, 세션 종료 또는 커밋 승인을 기다리지 않고 신속하게 기록하세요. 결정은 사용자 또는 위임된 권한 내에서 선택하는 에이전트로부터 올 수 있습니다. 기록은 승인 단계를 추가하지 않으며, 사용자의 결정을 아직 기다리는 트레이드오프는 메모를 작성하여 확정할 수 없습니다.
작성하기 전에 형식 및 예제를 읽으세요. 기본 위치는 대상 프로젝트의 .agents/notes/YYYY-MM-DD-topic.md이며, 기존 프로젝트 위치를 선호하세요. 파일당 하나의 결정 주제와 안정적인 경로를 유지하세요. 상태나 서브시스템별로 디렉토리에 노트를 정리하지 마세요.
- 제목,
상태및범위를 유지하세요. 본문을 결론, 근거 및 트레이드오프에 집중하고, 필요에 따라 다른 섹션을 추가하세요. 본문 텍스트는 프로젝트에 일관된 언어가 없으면 기본적으로 영어로 작성합니다. 대안을 만들거나, 고정된 개수를 요구하거나, 긍정적/부정적 결과 레이블을 강제하지 마세요. - 각 결론의 범위와 조건을 명시하세요. 채택되었지만 구현되지 않은 목표를 현재 구현, 마이그레이션 또는 배포 사실로 설명하지 마세요. 설계 및 계획 문서는 구현 진행 상황을 소유합니다.
- 근거가 누락된 경우 제공되지 않았거나 기록되지 않았다고 말하세요. 실패의 경우 조건, 결과 및 필요한 증거 또는 증거 격차를 유지하고, 영구적인 불가능성을 추론하지 마세요. 이후 세션에서 액세스할 수 없는 채팅이나 임시 출력에만 의존하지 마세요.
4. 업데이트, 대체 및 정리
| 상태 | 의미 |
|---|---|
active | 명시적으로 채택되었으며 명시된 범위 내에서 여전히 적용 가능; 유효한 거부 및 연기도 이 상태를 사용합니다 |
superseded | 전체 범위가 하나 이상의 새 결정으로 대체됨 |
retired | 유효한 내용이 없으며, 새 결정이 완전히 대체하지 않음 |
상태는 구현 진행 상황이나 후보 솔루션의 처분을 나타내지 않습니다. 사실, 이름, 경로 또는 증거가 변경되었지만 결정이 변경되지 않은 경우 기존 기록을 업데이트하세요. 핵심 선택 또는 제약 조건이 명확하게 변경되면 새 기록을 생성하세요. 증거가 유효하지 않게 되면 재평가하지만, 결정을 자동으로 변경하지 마세요.
상태 변경, 결정 대체, 부분 대체 처리 또는 오래된 옵션 복원 전에 상태 및 대체를 읽으세요. 범위별로 이전 및 새 기록을 상호 참조하고, 부분 대체 후에도 남은 제약 조건을 보존하세요. 오래된 옵션이 다시 채택되면 중간 결정을 지우지 않고 새 기록을 생성하세요.
보관, 병합 또는 삭제 전에 보존 및 정리를 읽으세요. 기본적으로 기록을 보존하세요. 논리적 보관은 경로를 이동하지 않으며, 병합은 진정한 결정 변경을 지워서는 안 되며, 삭제 전에 고유 정보를 마이그레이션하고 참조를 업데이트하세요. 현재 작업의 영향을 받는 기록만 정리하고, 전체 정리는 범위 내에 있어야 합니다.
5. 전달 전 확인
이 작업과 관련된 기록 및 관련 범위를 확인하세요. 새 노트가 생성되지 않은 경우에도 변경 사항이 기존 노트를 부정확하게 만들었는지 확인하세요.
- 누락 및 중복: 중요한 결론과 장기적인 근거가 저장되었습니까? 대화에만 있습니까? 기존 기록으로 충분합니까?
- 진실 및 증거: 권장 사항을 결정으로, 목표를 현재 상태로, 실패를 영구적인 거부로, 선택되지 않은 옵션을 금지된 것으로, 연기를 구현 약속으로 제시하지 마세요. 알 수 없거나, 제공되지 않았거나, 확인되지 않은 정보를 정확하게 명시하세요.
- 상태 및 범위: 범위와 조건이 정확합니까? 부분 대체가 남은 의무를 유지합니까? 동일한 범위와 조건에 대해 충돌하는 유효한 결론이 있습니까? 보관이 현재 제약 조건을 숨깁니까?
- 문서 소유권: 영향을 받는 서브시스템 문서, 설계, 계획 및 노트를 업데이트하세요. 각 소스는 자체 정보를 소유하며, 다른 위치는 이에 연결됩니다.
- 링크 및 대체 체인: 필요한 소스를 찾을 수 있습니까? 자기 참조 링크, 끊어진 링크 또는 순환 없이 범위별로 결론을 추적할 수 있습니까? 정리가 고유한 근거, 증거 및 의미 있는 기록 참조를 보존했습니까?
- 검증: 프로젝트에서 이미 사용 가능한 관련 검사를 실행하고 결과를 검토하세요. 구성된 것이 없으면 수동으로 확인하세요. 종속성, 스크립트, CI 또는 형식 마이그레이션을 자동으로 추가하지 마세요. 발견된 실제 문제를 수정하고, 내용을 조작하지 마세요. 관련 콘텐츠가 변경되지 않은 경우 성공적인 결과를 재사용하세요.
형식 검사를 통과했다고 해서 근거가 정확하거나, 검색이 완료되었거나, 구현이 결정을 따른다는 증거는 아닙니다. 현재 사실이 기록과 충돌하는 경우 전환 준비, 오래된 문서, 불완전한 구현 및 실제 충돌을 구분하세요. 확인된 오류를 수정하세요. 핵심 판단이 여전히 명확하지 않으면 충돌을 설명하고 결정을 요청하세요. 새로운 사용자 지침을 무시하거나 완료를 주장하지 마세요. 답변에 의존하지 않는 작업을 계속하세요.
노트를 추가, 대폭 업데이트, 대체 또는 정리할 때 변경된 내용, 이유 및 링크와 함께 모든 격차를 간략히 설명하세요. 관련된 내용이 변경되지 않았을 때 고정된 "추가된 노트 없음" 메시지를 내보내지 마세요.
코드, 관련 문서 및 노트를 하나의 보류 중인 인도물로 함께 유지하세요. 이번 라운드의 변경 및 확인을 완료하고 결과를 표시한 후, 작업이 완료되었는지와 로컬 커밋을 생성해도 되는지 물어보세요. 사용자가 추가 피드백을 제공하면 편집을 계속하세요. 노트를 저장하거나 검증한다고 해서 커밋, 푸시 또는 게시가 승인되는 것은 아니며, 조기 커밋이 필요하지도 않습니다.