---
title: "문제 해결하기"
description: "압박을 받는 상황에서도 문제를 효율적으로 진단하고 해결합니다."
doc_version: "2025-01-09"
last_updated: "2026-08-09"
canonical_url: "https://7act.org/ko/actions/troubleshoot/"
language: "ko"
license: "CC BY 4.0"
---

# 문제 해결하기

잘못된 설정이나 예외 상황, 실제 버그 때문에 문제를 만나는 것은 흔한 사용자 경험입니다. 문제 해결하기 행동은 시스템이 고장 났거나 마감이 임박하여 압박을 받는 상황에서도 문제를 효율적으로 진단하고 해결하려는 사용자의 요구를 나타냅니다.

문제 해결을 다루는 문서의 예로는 Kubernetes의 [Debug Pods](https://kubernetes.io/docs/tasks/debug/debug-application/debug-pods/)와 Elasticsearch의 [Troubleshooting](https://www.elastic.co/guide/en/elasticsearch/reference/current/fix-common-cluster-issues.html)이 있습니다. 가장 효과적인 문제 해결 문서는 흔한 문제와 해법을 나열하는 데 그치지 않습니다. 시스템이 예상대로 작동하지 않을 때 어떻게 생각해야 하는지를 사용자에게 가르칩니다.

이런 문서를 사후 대응용 자료로만 생각하기 쉽지만, 사용자에게 자신감을 심어 주는 데 큰 변화를 만들 수 있습니다. 사용자가 장애에서 복구하는 법을 이해하면 언제든 의지할 안전망이 있다는 사실을 알고 더 적극적으로 탐색하고 한계를 넓히게 됩니다.


## 사용자가 하려는 일

잘못된 설정이나 예외 상황, 실제 버그 때문에 문제를 만나는 것은 흔한 일입니다. 문제 해결하기는 시스템이 고장 났거나 마감이 임박한 상황에서도 문제를 효율적으로 진단하고 해결하려는 요구를 나타냅니다.

## 문서가 이 요구를 놓치고 있다는 신호

- 지원 요청에 같은 질문이 반복되지만 답은 문서가 아니라 채팅 기록에 있습니다.
- 오류 메시지는 코드에 있지만 문서에는 전혀 나오지 않습니다.
- 사용자가 오류 문자열을 검색해도 그 오류를 언급하지 않는 페이지에 도착합니다.

## 실제 사례 두 가지

- [Kubernetes Debug Pods](https://kubernetes.io/docs/tasks/debug/debug-application/debug-pods/)
- [Elasticsearch Troubleshooting](https://www.elastic.co/guide/en/elasticsearch/reference/current/fix-common-cluster-issues.html)

## 일반적인 콘텐츠 유형

- DITA: <troubleshooting>, <trouble>, <cause>, <remedy>
- Diataxis: 문제 중심 방법 안내서
- Good Docs Project: 문제 해결 안내서

## 하나의 지표

해결까지 걸린 시간 — 증상이 나타난 때부터 정상 상태로 돌아올 때까지 걸린 시간의 중앙값입니다.

## Sitemap

- [일곱 가지 행동 문서화 모델](https://7act.org/ko/index.md)
- [소개](https://7act.org/ko/rationale/index.md)
- [행동](https://7act.org/ko/actions/index.md)
- [평가하기](https://7act.org/ko/actions/appraise/index.md)
- [이해하기](https://7act.org/ko/actions/understand/index.md)
- [탐색하기](https://7act.org/ko/actions/explore/index.md)
- [연습하기](https://7act.org/ko/actions/practice/index.md)
- [기억하기](https://7act.org/ko/actions/remember/index.md)
- [개발하기](https://7act.org/ko/actions/develop/index.md)
- [문제 해결하기](https://7act.org/ko/actions/troubleshoot/index.md)
- [용어집](https://7act.org/ko/glossary/index.md)
- [일곱 가지 행동 문서화 Skill](https://7act.org/ko/skill/index.md)