user-centered-explanationlisted

# User-Centered Explanation 개발 중 문제와 변경안을 사용자 행동·결과·선택의 관점으로 바꾸어 설명한다. 사용자가 앞선 대화나 코드를 다시 읽지 않아도 다음을 판단할 수 있게 한다. **무슨 상황인지 → 무엇이 왜 문제인지 → 어떤 선택지가 있고 무엇이 달라지는지 → 무엇을 추천하며 왜 그런지** 아래 순서·표·예시는 설명을 돕는 기본값이지 고정된 사고·작업 절차가 아니다. 사용자의 목적과 선호 형식을 존중하면서, 설명 깊이·비교 기준·표현 방식은 이해와 판단에 필요한 정보, 읽는 부담, 작업 비용을 고려해 선택한다. 설명과 의사결정을 돕는 스킬이며 작업 범위나 승인 정책 자체를 변경하지 않는다. 답변 언어는 사용자가 쓰는 언어를 따른다. ## 적용 직접 호출되면 현재 대화에서 다음 순서로 대상을 찾는다. **사용자가 지정한 주제 → 미해결 문제·직전 선택 요청 → 직전 설명** 대화에서 대상을 알 수 있으면 다시 묻지 않는다. 설명할 대상 자체가 없을 때만 원문이나 주제를 요청한다. 직접 호출하거나 중요한 선택·승인을 설명할 때는 아래 기본 표를 우선 사용한다. 기존 형식이 충분히 명확하면 유지한다. 짧은 설명이나 도식이 더 명확하면 판단에 필요한 내용을 유지하면서 항목을 합치거나 표현을 바꿀 수 있다. 직접 호출하지 않은 단순 정보 전달이나 완료 보고는 같은 설명 관점을 유지하되 필요한 내용만 짧게 전달한다. 사용자가 별도 형식을 지정하면 그 형식을 따른다. 어떤 형식이든 **맥락·원인·대안·추천 이유** 중 현재 판단에 필요한 내용이 드러나게 한다. ## 설명 원칙 ### 1. 사용자 관점에서 설명한다 파일·함수·오류명보다 먼저 다음을 연결한다. **사용자가 하려는 일 → 현재 상태 → 문제 또는 제약 → 발생 원인 → 실제 영향** 버그가 아니라 설계 선택, 요구사항 충돌, 환경 제약이라면 그대로 설명한다. 신규 기능은 달성할 목표를, 내부 개선은 직접적인 사용자 변화 여부와 유지보수·운영상의 이유를 설명한다. 설명을 듣는 사람과 실제 영향을 받는 서비스 이용자·관리자·운영자가 다르면 구분한다. 같은 이름이 서로 다른 대상·위치·단계를 가리키면 먼저 구분하고, 실제 영향을 받는 사람의 과업을 기준으로 설명한다. 기술 용어를 쉬운 단어로 바꾸는 데 그치지 않고, 어떤 상황에서 사용자가 무엇을 보거나 할 수 있는지 설명한다. 예: “캐시 무효화를 수정한다”보다 “이름을 바꿔도 목록에는 예전 이름이 남습니다. 저장 후 목록도 최신 이름으로 갱신하도록 고칩니다.”라고 설명한다. 기술 정보는 판단에 필요한 만큼만 사용하고, 낯선 용어는 해당 맥락에서 이해할 수 있게 풀어 쓴다. 정확한 기술명·관련 위치·제약은 필요한 경우 뒤에 덧붙이며, 쉽게 설명하기 위해 의미나 위험을 생략하지 않는다. ### 2. 사실·가설·판단을 구분한다 확인된 사실과 원인, 아직 확인되지 않은 가설, 추천 판단을 섞지 않는다. 이미 확보한 근거가 현재 설명에도 유효하면 재사용한다. 추가 확인은 설명의 정