에이전트 노트
에이전트 노트는 결정 코퍼스를 작고 권위 있게 유지합니다. 각 노트는 코드와 문서가 전달할 수 없는 근거만을 기록하며, 그 외의 것은 기록하지 않습니다. 레이아웃, 클래스, 파일 내 형식에 대한 규칙은 .agents/notes/README.md에 있습니다. 이 스킬은 워크플로우를 담당합니다. 모든 노트를 의미론적으로 판단하세요. 단어 수와 작성일은 발견을 위한 도우미일 뿐, 기준이 아닙니다. 이는 지침이지 체크리스트가 아닙니다.
노트 필요성 판단
영구적인 결정 근거(왜 하나의 설계가 선택되었는지, 무엇을 포기했는지, 어떤 대안이 탈락했고 그 이유는 무엇인지, 어떤 검증이 이를 뒷받침하는지)에 대해서만 노트를 작성하거나 업데이트하세요. 기계적이거나 로컬 편집(로컬 UI 표시 변경 포함), 또는 코드, API 문서, README, 쿡북에 속하는 사실에 대해서는 노트를 작성하지 마세요.
- 실질적인 향후 작업에 대한 제안은
proposed/<class>/로 이동하고, 현재 변경에서 결정된 사항은implemented/<class>/로 이동합니다. - 활성 노트가 이미 해당 결정을 소유하고 있다면, 중복 생성 대신 해당 노트를 업데이트하세요.
- 결정의 반전은 이전 노트를 상호 참조하는 새 노트를 작성해야 합니다. 기존 노트를 다른 결정으로 편집하지 마세요.
노트 작성
.agents/notes/README.md의 표에서 클래스를 선택하고 파일 이름을yyyy-mm-dd-주제-제목.md형식으로 지정하세요. 주제가 처음 제안된 날짜를 사용합니다.- README의 정확한 헤더와 생애주기별 섹션 골격을 사용하세요.
## 고려한 대안은 필수입니다. 각 실제 대안과 그것이 탈락한 이유를 기록하고, 대안을 지어내지 마세요. - 구현된 노트는 현재 시제로 작성하여 출시된 현실을 설명하세요. 계획, 수락 체크리스트, '~해야 한다' 등의 표현은 사용하지 마세요. 동작을 고정하는 검증과 명명된 적용 범위 격차를 기록하세요.
- 다른 노트와 문서를 상대 Markdown 링크로 연결하세요. 산문 표준과 trim-cot-leakage를 따르세요. 노트 자체의 변경 내역 섹션 외부에는 검토 코레오그래피, 세션 인용, 변경 내레이션을 포함하지 마세요.
모든 새 노트에 대한 대체 확인
작성 전에 활성 트리(proposed/, implemented/, rejected/)에서 동일한 결정, 메커니즘 또는 거부된 대안을 다루는 노트를 검색하세요. 새 노트를 작성하는 동안 각 일치 항목을 분류하세요:
- 구현된 노트의 완전 대체: 통합(새 노트가 모든 고유한 근거, 대안, 결과, 검증 및 적용 범위 격차를 보존한 후, 이전 노트는 삭제되고 인바운드 링크는 수정됨)하거나 동일한 변경에서 보관합니다.
- 부분 대체: 둘 다 활성 상태로 유지하고 상호 참조하며, 현재 유효한 모든 사실을 업데이트합니다.
- 구식 제안: 정직한 한 줄 이유와 함께
rejected/로 이동합니다. - 구식 거부: 더 이상 그럴듯한 실수를 방지하지 않으면 삭제합니다.
알려진 일치 항목을 나중 감사로 미루지 마세요.
미래 가치에 따른 기존 노트 분류
감사 또는 정리 시 각 생애주기에 따라 다음 결과를 적용하세요:
- 구현됨, 삭제: 작은 UI 조정이나 순전히 기계적인 변경만 설명하는 노트. 인바운드 링크를 수정하거나 제거하세요. 로컬 버그 수정, 성능 변경, 새로운 기능, 실질적인 동작 또는 소유권 결정은 구현 규모가 작다는 이유만으로 삭제 대상이 아닙니다. 유지 또는 보관 전에 이 테스트를 적용하세요.
- 구현됨, 활성 유지: 향후 변경을 안내할 가능성이 있는 근거, 대안, 부정적 보증, 내구성 또는 와이어 시맨틱스, 소유권 경계, 보안 규칙 또는 재도입 조건. 구현 규모가 아니라 결정 자체를 분류하세요. 기계적 이름 변경이라도 영구적인 명명 또는 호환성 규칙을 기록할 수 있습니다.
- 구현됨, 보관: 완료되었고 향후 작업을 안내할 가능성이 낮지만, 근거를 보존할 가치가 있는 실질적인 역사적 결정.
- 제안됨, 절대 보관 금지: 라이브 제안을 활성 상태로 유지하세요. 더 이상 추구할 가치가 없으면 정직한 이유와 함께 거부하세요.
- 거부됨, 가드레일로만 유지: 패배한 제안이 계속해서 유혹적이고 의미 있는 실수로 남아 있고 노트가 그 이유를 설명하는 경우에만 거부를 유지하세요. 그렇지 않으면 삭제하세요.
할당량을 맞추기 위해 보관하지 마세요. 범위 내 모든 노트를 검사하고, 유사한 그룹을 하나의 원칙으로 분류하며, 진정으로 경계에 있는 결정은 보고서에 기록하세요.
보정: 접힌 사이드바 컨트롤의 스타일링에 대한 노트는 아무리 길어도 삭제됩니다. 세션이 이벤트 소싱된다는 것을 확립하거나 스토리지 디렉토리의 단일 소유자를 명명하는 노트는 아무리 짧아도 활성 상태로 유지됩니다. 두 패키지를 병합해서는 안 되는 이유를 기록하는 노트는 병합이 계속 유혹적인 동안 가드레일로 유지됩니다.
구현된 노트 보관
- 번역된 버전이 있다면 함께
implemented/<class>/에서archived/<class>/로 완전한 노트를 이동하세요. - 본문 편집을 하지 마세요. 각 언어 파일의
Status: implemented바로 아래에Archived: YYYY-MM-DD를 동일한 날짜로만 삽입하세요. - 활성 산문에서 인바운드 링크를 검색하세요. 현재 권위로 리디렉션하거나, 역사적 스냅샷을 의도적으로 인용하는 경우에만 보관된 경로로 재타겟팅하거나, 링크를 삭제하세요. 보관된 노트의 링크를 확인하거나 수정하지 마세요.
보관 후에는 노트를 편집, 이동, 번역, 재포맷 또는 삭제하지 마세요. 보관된 노트는 유효한 링크 대상으로 남아 있지만 현재 동작에 대한 권위는 아닙니다.
검증 및 보고
프로필의 commands.docs-check와 git diff --check를 실행하고, 변경된 모든 상대 링크가 확인되는지 확인하세요. 생성 또는 업데이트된 노트, 활성 상태로 유지된 노트, 삭제, 보관 또는 거부된 노트, 그리고 선택된 결과와 함께 모든 경계 사례를 보고하세요.