---
name: gitops-change
description: >
  클러스터에 떠 있는 것을 바꿔야 할 때 — kubernetes 도구로 직접 고치기 전에 —
  로드한다. 리소스·설정·복제 수·이미지 버전 변경을 클러스터가 아니라 GitOps
  저장소의 chart values 변경으로 옮기고, 어느 파일을 고쳐 어떻게 PR을 올릴지 정한다.
---

# GitOps 변경

**클러스터를 직접 바꾸지 않는다.** 변경은 저장소를 고치는 일이고, 반영은 Argo CD가
한다.

이유는 Argo Application이 `selfHeal: true`, `prune: true`로 돌고 있어서다.
클러스터에 직접 넣은 변경은 저장소와 어긋나는 순간 다음 sync에 되돌려진다.
kubernetes 도구에 워크로드 쓰기(create·update·patch)가 열려 있어도 마찬가지다 —
`kubectl apply`든 도구 호출이든, 저장소를 거치지 않은 변경은 답이 아니다.

## 반드시 지킬 것

- 변경 요청을 받으면 **어느 파일의 어느 값을 바꿀지**로 번역한 뒤 시작한다.
- 저장소 구조를 짐작하지 않는다. 해당 저장소의 README와 실제 `charts/` 아래를
  확인하고 나서 파일을 골라라. 아래 규칙은 현재 `argocd-env-demo` 기준이다.

## 어느 파일을 고치나

```
charts/<project>/
  values.yaml                  # 모든 phase 공통
  values-<phase>.yaml          # 특정 phase. 배포 파이프라인이 갱신하는 파일
  <env>/values-<cluster>.yaml  # 특정 클러스터
apps/<name>.yaml               # ApplicationSet (새 앱을 추가할 때)
```

| 바꾸려는 것 | 고칠 파일 |
|---|---|
| 모든 환경에 적용될 설정 | `charts/<project>/values.yaml` |
| 한 phase에서만 다른 값 | `charts/<project>/values-<phase>.yaml` |
| 한 클러스터에서만 다른 값 | `charts/<project>/<env>/values-<cluster>.yaml` |
| 새 앱 추가 | `apps/<name>.yaml` + `charts/<name>/` |

아래에서 덮어쓰므로, **가장 좁은 범위의 파일에 넣는다.** 한 클러스터만 고치면
되는 값을 `values.yaml`에 넣으면 전 환경이 따라 움직인다.

## 이미지 버전은 손으로 고치지 않는다

배포 파이프라인이 `repository_dispatch`로 `values-<phase>.yaml`을 갱신한다. 같은
파일을 사람이 동시에 고치면 충돌하거나 다음 배포에 덮인다.

버전을 올려 달라는 요청은 파일 수정이 아니라 **배포를 트리거하는 일**이다. 직접
값을 바꾸기 전에 그게 맞는지 확인한다.

## PR

`prod`는 PR을 거치고 나머지 phase는 main에 바로 반영된다. **어느 쪽이든 사람의
승인 없이 푸시하지 않는다.**

### 어떻게 올리나

이 플러그인의 `github` MCP 서버로 한다. 순서는 이렇다.

1. 고칠 파일의 현재 내용을 읽는다. 짐작한 값으로 덮어쓰지 않는다.
2. 브랜치를 만든다. main에 직접 커밋하지 않는다.
3. 바뀐 값만 담아 커밋한다. 한 PR에 한 목적이니 무관한 파일을 같이 넣지 않는다.
4. PR을 만들고 URL을 사용자에게 준다.

**1번까지는 조사이고 2번부터는 쓰기다.** 2번 앞에서 무엇을 어느 파일에 넣을지 사용자에게
보이고 승인을 받는다. 도구 이름과 파라미터는 시스템 프롬프트의 실제 tool schema를
진실로 삼고, 없는 도구 이름을 만들어내지 않는다. `github` 서버가 연결돼 있지 않으면
변경할 파일 경로와 최종 내용, PR 본문 초안까지 만들어 주고 올리는 것은 사용자가 한다.

### 본문

`engineering` 플러그인의 `pr-description`이 연결돼 있으면 그 구조를 따른다. 없으면
아래 네 가지를 담는다.

- **무엇을** — 바뀐 값과 파일
- **왜** — 어떤 문제를 해결하거나 무엇을 가능하게 하는지
- **영향 범위** — 어느 phase, 어느 클러스터, 재시작이 필요한지
- **되돌리는 법** — revert로 충분한지, 아니면 추가 조치가 필요한지

한 PR에 한 목적만 담는다. 조사하다 발견한 다른 문제는 별도 PR로 분리하고 본문에
언급만 한다.

본문은 리뷰어가 30초 안에 읽고 승인 여부를 정하는 글이다. 문장은 이렇게 쓴다.

- 한 문장에 사실 하나. 값·파일·phase·리소스 이름이 문장 안에 보이게 쓴다.
- "개선", "최적화", "안정화", "정상화" 대신 무엇이 어떻게 바뀌는지 적는다.
  "리소스 최적화" → "`memory.limit` 을 512Mi 에서 1Gi 로".
- "~할 수 있습니다", "~것으로 예상됩니다"로 흐리지 않는다. 확인한 것은 단언하고 확인 못 한
  영향은 "확인 못 함"으로 밝힌다.
- "단순히 A가 아니라 B", "결론적으로", "다음과 같은", "이를 통해", 문두 "또한·따라서"를 쓰지
  않는다. "-고,", "-지만," 연결어미 뒤 쉼표도 뺀다.
- 이모지, 볼드 강조, "X: Y" 콜론 부제, "다음은 변경 내용입니다" 같은 챗봇 문구를 넣지
  않는다. 위 네 항목의 라벨과 백틱만 서식이다.

전체 패턴 목록과 전후 예시는 이 저장소의
`plugins/workspace/skills/korean-humanize/ai-tell-catalog.md` 가 source 다. 인라인 규칙과
카탈로그가 어긋나면 카탈로그가 이긴다.

## 반영 확인

머지가 곧 반영은 아니다. Argo가 sync한 뒤에 확인한다.

1. 저장소에 머지됐는가
2. Argo가 그 revision을 sync했는가
3. 클러스터에서 실제로 바뀌었는가 (kubernetes 도구로 관측)
4. 의도한 효과가 났는가 (grafana로 지표 확인)

3까지만 보고 "적용됐다"고 말하지 않는다. 뜬 것과 동작하는 것은 다른 얘기다.

## 되돌릴 때

- 되돌리는 것도 커밋이다. 클러스터에서 손으로 원복하면 다음 sync에 다시 돌아온다.
- `prune: true`라서 저장소에서 리소스를 지우면 클러스터에서도 사라진다. 파일을
  지우는 변경은 영향 범위를 먼저 밝히고 확인을 받는다.
- 급한 완화가 필요하면 무엇을 임시로 했는지 명시하고, 저장소에 반영할 후속 작업을
  같이 남긴다.