포스트

결과만 기록하는 팀, 과정까지 남기는 팀

게시 업데이트
By Juho
7 분읽는 시간

목차

  1. 글을 쓰게 된 사소한 계기
  2. 탐색 중심 문서화
  3. 성공 중심 문서화
  4. 균형 잡기

글을 쓰게 된 사소한 계기

팀에서 문제 해결 과정을 기록할 때 저는 “탐색 과정까지 남겨야 한다”고 생각한다.
하지만 팀의 다른 분은 “성공한 결과만 정리하자”고 하셨다.
“문서의 목적은 결과를 공유하는 걸까, 아니면 학습을 공유하는 걸까?”라는 고민을 하게 되었다.
결론만 깔끔하게 쓸까? 아니면 시행착오까지 남겨야 할까? 그 고민에 대한 내용이다.

탐색 중심 문서화

실패와 시도 과정을 포함하는 방식 → 우리가 왜 그렇게 했는가

장점

  1. 문제 해결의 맥락 보존
    단순히 “무엇을 했다”가 아니라 “왜 그렇게 했는가”가 남는다.
    예를 들어 “A 라이브러리를 시도했지만 B 버전과 충돌 → C로 변경”
    이런 맥락이 있어야 다음에 비슷한 문제가 발생해도 같은 실수를 반복하지 않는다.

  2. 재현성과 확장성 확보
    후임자나 다른 팀이 동일한 문제를 다시 겪을 때 “똑같이 삽질하지 않고” 빠르게 우회할 수 있다.
    DevOps, ML, 인프라 등 환경 의존적인 영역에서 특히 중요하다.

  3. 학습 가치가 높음 실패 원인과 시도 과정을 분석하면서 팀이 함께 배우는 학습 자산이 된다.
    때로는 성공의 이유보다 실패의 이유가 더 큰 인사이트를 준다고 생각한다.

단점

  1. 시도 과정이 길어질수록 가독성이 떨어짐
  2. 문서 업데이트와 유지보수에 시간이 많이 듦
  3. 사소한 시행착오까지 기록되면 핵심이 묻힐 수 있음

성공 중심 문서화

결론과 Best Practice 중심 → 이 문제를 해결하려면 이렇게 하라

장점

  1. 정보 접근성이 높음
    바쁜 동료도 필요한 정보를 빠르게 찾을 수 있다.
    매뉴얼, 온보딩 자료, 레퍼런스 문서로 활용하기 좋다.

  2. 일관성과 신뢰성 유지
    모든 문서가 “검증된 결과”만 다루기 때문에 신뢰도와 품질이 일정하다.

  3. 시간 절약 & 관리 효율성
    세세한 과정 생략 → 작성과 유지보수가 빠르다.

단점

  1. 맥락 손실: “왜 이 방법을 택했는가”가 빠져 있음
  2. 재발 가능성: 실패 이유가 없어 같은 문제를 반복할 수 있음
  3. 학습 깊이 부족: 단순한 ‘정답집’이 되어 팀의 문제해결 역량이 성장하지 않음

균형 잡기

가장 이상적인 방식은 둘을 분리하지 않고 결합하는 것이다.
내가 생각한 문서화 템플릿이다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

# 문제 제목
> CI 파이프라인에서 테스트 단계가 무작위로 실패하는 문제

---

## 요약
- **결론:** 테스트 컨테이너의 메모리 리밋이 부족해서 간헐적 실패 발생 → 리밋 1GB로 상향 후 해결  
- **핵심 조치:** `.gitlab-ci.yml` 수정  
- **적용일:** 2025-11-05  
- **적용 범위:** Backend / QA 서버  

---

## 문제 상황 
- CI 환경에서 테스트가 랜덤하게 실패  
- 로컬에서는 동일 테스트 모두 통과  
- 테스트 로그에 `Killed` 메시지 존재  

---

## 탐색 및 시도
| 시도 번호 | 접근 방식 | 결과 | 배운 점 |
|------------|------------|--------|-----------|
| 1 | 테스트 스크립트 병렬 실행 제한 | 실패 | 실패 패턴에 변화 없음 |
| 2 | DB 커넥션 풀 조정 | 실패 | 테스트 도중 컨테이너 종료 현상 동일 |
| 3 | 리소스 모니터링 추가 | 발견 | 테스트 단계에서 메모리 초과로 OOM 발생 |
| 4 | CI 컨테이너 메모리 리밋 조정 | 성공 | 이후 10회 연속 테스트 통과 |

---

## 최종 해결
- `.gitlab-ci.yml` 내 `services.mem_limit` 항목을 `1g`로 변경  
- 테스트 컨테이너 환경 변수 `NODE_OPTIONS=--max-old-space-size=512` 추가  
- CI 파이프라인 정상 동작 확인  

---

## 참고 & 연관 이슈
- 관련 티켓: [#1234](https://issue-tracker.com/1234)
- 참고 문서: [GitLab CI Docs: Memory Limits](https://docs.gitlab.com/ci/)

궁극적으로 중요한 건 “읽는 사람의 맥락”을 고려하는 것이라고 생각한다.
단순한 결과만 남기면 지식은 사라지고 시도만 남기면 혼란이 생긴다.

Dev
Dev 개발 문서화 지식 자산화