유지보수 문서

유지보수 문서은(는) 무엇을 하나요?

1. 책임과 현재 범위 명확히 하기

이 스킬은 레코드를 생성하거나 재사용할지 결정하고, 콘텐츠를 구성하고, 설명을 검증하고, 공백을 드러내고, 소스 관계, 상태 및 탐색을 유지하는 데 사용합니다. 이를 위해서는 엔지니어링 판단이 필요합니다. 현재 메커니즘을 설명할 때는 실제 경로를 조사하고, 단순히 대화를 다시 포맷하거나 템플릿을 채워 거짓 확신을 만들어서는 안 됩니다.

• 현재 작업을 수행하는 에이전트는 기술적 선택, 트레이드오프, 작업 분할, 구현, 디버깅 및 검증을 처리합니다. 출력을 보존해야 할 때 이러한 공유 규칙을 사용합니다. 대상 조사 및 서브시스템 문서 업데이트는 유효한 작업이며, 별도의 설계 프로세스를 먼저 시작할 필요가 없습니다.
• to-docs를 사용하여 사람이 검토, 편집 및 나중에 참조할 수 있는 읽기 쉬운 설계 산출물을 만듭니다. 사람이 읽을 수 있는 설계는 완전한 소스가 될 수 있습니다. 이 스킬은 저장되는 시점부터 문서 소유권과 일관성을 안내합니다. 먼저 엔지니어링 레코드를 요구하거나 스킬 간 순환 호출을 생성하지 마십시오.
• grilling을 사용하여 현재 주제를 심층적으로 명확히 합니다. grill-me가 명시적 진입점입니다. 결정을 다시 열거나 각 반복에 승인 게이트를 추가하지 않고 설정된 콘텐츠에서 계속 진행합니다.
• decision-notes를 사용하여 장기적인 결정을 찾고, 기록하고, 대체하고, 구성합니다. 이 스킬은 그 결론을 참조합니다. 별도의 인터뷰 프로세스나 결정 수명 주기를 설정하지 않습니다. 트리거 조건이 적용될 때 직접 링크가 없더라도 검색합니다.
• 필요에 따라 handoff를 사용하여 세션 또는 에이전트 간 핸드오프를 준비하거나 확인합니다. 이 스킬은 엔지니어링 자료와 상태를 계속 유지 관리합니다. 작업을 실행하는 사람이 변경되었다고 해서 완전한 복제본을 만들지 말고, 스킬 간 순환 호출을 만들지 마십시오.
• 일반적인 읽기, 즉각적인 질문 및 기존 자료에 영향을 미치지 않는 작은 변경은 독립적으로 전체 유지보수 프로세스를 트리거하지 않습니다. 그래도 작업에 필요한 자료는 읽습니다. 문서 전용 요청은 제품 동작을 변경하거나, 관련 없는 검사를 실행하거나, 코드를 커밋할 권한을 확장하지 않습니다. 기존 엔지니어링 작업 권한은 그대로 유지됩니다.

환경에서 실제로 사용 가능한 이름을 사용하십시오. 스킬을 호출할 수 없으면 프로젝트의 구성된 가이드를 대신 읽으십시오. 사용할 수 없는 스킬을 호출했다고 주장하지 마십시오. 협업은 순환 로딩이나 중복 검색을 유발해서는 안 됩니다.

2. 소스 찾기 및 레코드 재사용 또는 생성 결정

프로젝트의 실제 에이전트 진입점에서 시작하여 제약 조건, 요구 사항 및 승인 기준, 관련 서브시스템, 변경 레코드 및 노트를 찾습니다. 현재 작업의 범위를 확인합니다. 기존 프로젝트의 경우 기존 위치와 이름을 선호합니다. 마이그레이션을 요구하지 마십시오. 교차 서브시스템 작업의 경우 관련 인터페이스와 공유 제약 조건을 다룹니다.

동일한 작업에 대해 이미 읽고 확인된 컨텍스트가 여전히 적용되는 경우 재사용합니다. 범위, 주요 전제 또는 소스가 변경되거나 충돌이 나타나면 영향을 받는 영역을 다시 확인하십시오. 턴이나 스킬이 변경되었다고 해서 전체 저장소를 다시 스캔하거나 인터뷰를 다시 시작하지 마십시오.

위치, 이름, 파일 분할 또는 탐색을 선택할 때는 조직 및 소스를 읽으십시오.

1. 먼저 동일한 변경에 여전히 적용되는 기존 문서를 찾으십시오. 유사한 주제가 반드시 동일한 변경을 의미하는 것은 아닙니다. 기존 작업을 계속하려면 원본 레코드를 찾고 현재 상태를 확인한 후 완전한 핸드오프 문서를 자동으로 작성하지 마십시오.
2. 대상 설계, 마이그레이션 계획, 종속성 또는 조사 및 확인해야 할 질문을 나중에 구현, 승인 또는 교차 세션 지속을 위해 보존해야 할 때 레코드를 생성하거나 업데이트하십시오. 이는 조사 및 솔루션 비교 중에도 적용됩니다.
3. 현재 턴에서 완료된 작고 명확한 변경 사항은 대화만으로 전달할 수 있지만, 기존 문서와 설정된 규칙에 따라 필요한 노트는 계속 유지 관리해야 합니다. 사용자가 명시적으로 저장을 요청하면 적절한 기존 소스를 선호하여 기록하십시오.
4. 라인 수, 파일 수, 대화 턴 또는 커밋 수에 따라 기계적으로 레코드를 생성하지 마십시오. 빈 페이지나 전체 문서 라이브러리를 미리 생성하지 말고, 문서를 작성할 때마다 묻지 마십시오.

3. 목적에 따라 자료 검증 및 유지 관리

현재 작업	필요에 따라 읽기	정보 소유권
사람이 읽을 수 있는 설계와 엔지니어링 자료 간의 소유권 및 정렬 확인	조직 및 소스	사람이 읽을 수 있는 설계는 목표, 시나리오 및 동작에 대한 완전한 소스를 유지합니다. 엔지니어링 자료는 이를 참조하고 보완합니다.
현재 서브시스템 설명 또는 문서와 구현 간의 차이점 수정	서브시스템 문서	현재 책임, 메커니즘, 계약 및 소스 코드, 테스트, 노트에 대한 탐색
변경 목표, 설계, 작업 및 지속 컨텍스트 기록	변경 설계 및 계획	현재 목표, 기존 상태와의 차이, 미해결 질문, 구현 및 검증 계획
상태 업데이트, 레코드 완료, 일시 중지, 취소, 재개 또는 종료	상태 및 종료	전체 진행 상황, 작업 결과, 실제 검증 및 남은 작업 처리

각 사실은 한 곳에서 유지 관리하고 다른 곳에서는 요약 및 링크하십시오. docs/designs/<topic>.md는 완전한 사람이 읽을 수 있는 설계 소스가 될 수 있습니다. 엔지니어링 세부 사항, 종속성, 검증 및 진행 상황은 필요한 경우에만 .agents/changes/에 추가하고 설계를 복제하지 마십시오. 기존 소스의 개요를 완전한 복사본으로 만들거나, 인덱스에 두 번째 상태 또는 진행 레코드를 만들거나, 노트 소스 외부에서 장기적인 근거를 유지하지 마십시오.

엔지니어링 변경 진입점, README, 계획 및 전체 상태 규칙은 엔지니어링 변경 레코드가 필요한 작업에만 적용됩니다. 사람이 읽을 수 있는 설계에는 적용되지 않습니다. 설계의 확정되거나 미해결된 콘텐츠는 엔지니어링 진행 상황이 아닙니다. 필수 설계 상태 머신을 도입하거나 모든 설계에 대해 동반 엔지니어링 디렉토리를 만들지 마십시오.

확정된 결론, 미해결 권장 사항, 가정 및 조사 항목을 소스 코드 검증, 기존 테스트 적용 범위 및 실제 런타임 검증과 구분하십시오. 링크는 지원하는 메커니즘, 적용된 동작 또는 결정 주제를 설명해야 합니다. 테스트가 존재한다고 해서 성공적으로 실행되었다는 것을 의미하지는 않습니다. 목표를 채택했다고 해서 구현되었거나 전환 또는 호환성 의무가 자동으로 제거되는 것은 아닙니다.

문서와 구현이 일치하지 않으면 관련 소스 코드, 테스트, 요구 사항, 적용 가능한 노트 및 구현 상태를 확인하십시오. 문서가 오래되었는지, 구현이 의도된 동작에서 벗어났는지, 전환이 불완전한지 확인하십시오. 확인된 문서 오류를 수정하고 기존 권한 내에서 구현 오류를 해결하십시오. 결함을 정상적인 계약으로 설명하거나 오래된 문서를 사용하여 새로운 사용자 지시를 무효화하지 마십시오. 주요 동작이나 트레이드오프가 여전히 불명확하면 충돌을 설명하고 해당 결정에 의존하지 않는 작업을 계속하는 동안 사용자에게 결정을 요청하십시오.

4. 실질적인 변경 사항과 자료 동기화 유지

• 서브시스템 책임, 경계, 주요 경로, 인터페이스, 상태, 실패 동작, 호환성 동작 또는 필요한 탐색이 변경되면 프로젝트가 완료될 때까지 기다리지 말고 확인된 변경과 함께 관련 문서를 업데이트하십시오. 내부 리팩토링 후에도 정확한 설명을 기계적으로 다시 작성하지 말고 끊어진 링크는 수정하십시오.
• 목표, 범위, 주요 선택 또는 전제가 명확하게 변경되면 설계를 업데이트하고 미해결 콘텐츠는 계속 미해결로 표시하십시오. 작업 결과, 종속성, 차단 항목 또는 다음 단계가 실행 또는 지속에 영향을 미치는 방식으로 변경되면 계획을 업데이트하십시오. 영향을 받는 단계를 실행하기 전에 중요한 일정 변경 사항을 동기화하고 모든 도구 작업을 기록하지 마십시오.
• 기존 권한 내에서 조정을 자율적으로 처리하십시오. 문서 업데이트는 승인 요구 사항을 추가하지 않으며 필요한 사용자 결정을 대체할 수 없습니다. 권한을 초과하는 동작, 범위 또는 주요 트레이드오프 변경에 대해서는 사용자에게 결정을 요청하고 결정된 사항을 재확인하지 마십시오.
• 전달, 일시 중지 또는 핸드오프 전에 지속적인 유지가 필요한 관련 자료가 다음 에이전트가 현재 상태, 목표와의 차이, 남은 작업 및 다음 단계를 식별할 수 있도록 하십시오. 이러한 시점까지 기다려 첫 번째 레코드를 만들지 마십시오.

현재 작업과 관련된 범위만 처리하십시오. 현재 사실은 서브시스템 문서에, 장기적인 결정은 decision-notes에 유지하고 다른 위치는 이를 참조하도록 하십시오.

5. 확인 및 전달

이 작업에 대해 합의된 범위를 확인하십시오. 이를 저장소 전체 감사로 전환하지 마십시오.

1. 범위 및 소유권: 지속되어야 할 콘텐츠를 유지하십시오. 중복된 산문, 빈 자리 표시자 또는 임시 대화에만 남은 지속 컨텍스트 없이 적절한 소스를 재사용하십시오.
2. 정확성: 현재 상태, 목표, 확정 및 미해결 사항, 증거를 명확히 하십시오. 단계 진행, 코드 변경, 성공적인 검증 및 필수 수동 승인을 혼동하지 마십시오.
3. 상태 및 지속: 엔지니어링 변경 레코드가 존재하면 변경 진입점에서만 전체 상태를 유지 관리하고 실제 진행 상황에 따라 작업을 표시하십시오. 관련 차단 항목, 차이, 다음 단계 및 남은 작업을 찾을 수 있게 하고 종료 레코드에 필요한 결론과 증거를 보관하십시오.
4. 링크 및 일관성: 관련 요구 사항 및 승인 기준, 설계, 계획, 서브시스템 및 노트를 정확하게 연결하고 링크가 작동하는지 확인하십시오. 자료 또는 레코드를 재구성할 때 고유 정보가 손실되지 않아야 합니다.
5. 검증 범위: 작업 및 프로젝트를 기반으로 적용 가능한 기존 검사를 실행하고 결과를 검토하십시오. 전용 도구가 없으면 수동 검토를 수행하십시오. 문서를 완료하기 위해 관련 없는 검사, 전체 테스트 스위트 또는 새로운 도구 체인을 부과하지 마십시오. 콘텐츠가 변경되지 않은 경우 검증된 결과를 재사용하고 검증되지 않았거나 제한된 영역을 정확하게 설명하십시오.

현재 문서 작업을 완료한다는 것은 합의된 정보가 정확하고, 소스를 찾을 수 있고, 알려지지 않은 사항과 검증 격차가 공개되고, 자료가 지속을 지원한다는 것을 의미합니다. 설계가 충분하고, 구현이 정확하거나, 기능이 완료되었음을 증명하지는 않습니다. 상태 및 종료를 사용하여 전체 변경의 완료를 별도로 확인하십시오.

이번 라운드의 변경 사항, 검사 및 필요한 격차를 간결한 설명과 실제 파일에 대한 링크와 함께 전달하십시오. 지속적인 유지 관리가 필요한 결과는 저장소에 넣으십시오. 관련 코드, 문서 및 노트를 보류 중인 전달물로 함께 유지하십시오. 문서를 저장한다고 해서 커밋, 푸시, PR 또는 릴리스가 승인되는 것은 아닙니다. 프로젝트의 기존 커밋 확인 규칙을 따르고 문서가 저장되었다고 해서 일찍 커밋하지 마십시오.