# 하네스 스스로 개선하기

시행착오와 작업 피드백을 바탕으로 하네스를 점진적으로 개선하는 루프를 다룹니다.

원본 URL: https://abc.noco.kr/harness-basics/self-improve

[룰](/glossary#rules)과 [스킬](/glossary#skills)을 한 번 만들어 끝내면 다음 작업은 같은 시행착오를 반복한다. 개선의 대상은 만들어진 파일만이 아니다. 에이전트가 일하는 환경 자체다. 실패와 반복이 남을 때마다 무엇을 고칠지 정해 두면 환경이 따라온다.

기준일: 2026-09-30

## 만들고 끝내지 않는 루프

작업은 대체로 이 순서를 반복한다.

```mermaid
flowchart LR
  A[작업] --> B[실패와 반복]
  B --> C[해결]
  C --> D{다음에도 같은가}
  D -->|아니오| E[그대로 둔다]
  D -->|예| F[환경에 반영]
  F --> G[Rule·Skill·Docs·ADR·Test·Script]
  G --> A
```

해결이 곧 끝이 아니다. 같은 문제가 다시 나오면 그건 한 번의 일이 아니라 환경의 문제로 본다. 반대로 한 번뿐인 일은 환경에 넣지 않는다. 남길수록 읽는 사람이 줄어들고, 나중에는 무엇을 지웠는지 알 수 없다.

## 기록할 위치와 내용

남길 대상을 정해 두지 않으면 같은 내용이 여러 곳에 흩어진다. 판단 기준은 짧게 세 가지다. 항상 필요한가, 반복되는가, 팀이 알아야 하는가.

| 남길 내용 | 남기는 곳 | 예 |
|---|---|---|
| 항상 필요한 짧은 규칙 | [룰](/glossary#rules) | `pnpm`만 사용한다 |
| 반복되는 작업 절차 | [스킬](/glossary#skills) | REST API를 만드는 순서 |
| 개인 선호와 피드백 | [메모리](/harness-basics/memory) | 말투와 코드 스타일 |
| 프로젝트 지식 | [문서](/harness-basics/docs) | 빌드 명령과 배포 대상 |
| 중요한 결정 | [문서](/harness-basics/docs)의 기록 | 결제 제공자 선정 |
| 다시 하면 안 되는 오류 | 테스트·린트 | 파서 버그 재발 방지 |
| 반복되는 정해진 작업 | 스크립트 | 파일 일괄 변환 |
| 특정 시점 자동 실행 | [훅](/harness-advanced/hooks) | 편집 뒤 포맷 실행 |

왼쪽 열이 옆에 있으면 왼쪽에 남긴다. 개인 취향이 문서에 있으면 문서가 제안처럼 읽히고, 반드시 지킬 규칙이 개인 기억에만 있으면 다른 사람이 볼 때 빠진다. 판단이 애매하면 [메모리](/harness-basics/memory) 페이지를 다시 본다.

## 자동화와 확인의 구분

환경을 고치는 일은 대부분 자동화할 수 있지만, 전부를 자동화하면 원인을 잃는다. 판단의 무게에 따라 나눈다.

| 대상 | 처리 방식 |
|---|---|
| 관례 보강 | 자동 |
| 테스트 추가 | 자동 |
| 문서 갱신 | 자동 |
| 배포 정책 변경 | 사람 확인 |
| 보안 정책 변경 | 사람 확인 |
| 권한 범위 확대 | 사람 확인 |

에이전트에게 반복 규칙을 추가하라고 요청해 규칙이 늘어나는 것은 괜찮다. 하지만 권한이나 배포를 넓히는 요청은 별도로 검토한다. 같은 요청 안에 섞어 두면 넓히는 부분까지 함께 처리된다. 이 구분은 [보안](/harness-basics/security) 페이지의 원칙과 같은 방향이다.

## 추가와 정리

환경을 개선할 때 빠지기 쉬운 동작이 있다. 잘못된 내용을 계속 쌓는 것이다. 그래서 네 가지 동작을 함께 쓴다.

| 동작 | 언제 |
|---|---|
| 추가 | 새 상황이 생겼을 때 |
| 갱신 | 기존 항목이 틀렸을 때 |
| 통합 | 두 곳에 흩어진 내용을 한곳으로 |
| 제거 | 더 이상 필요 없는 내용 |

제거가 빠지면 파일이 부풀어 읽는 비용만 든다. 파일을 줄이는 것도 개선이다. 이 저장소는 룰 파일의 길이를 정해 두고, 그 수치를 넘으면 내용을 스킬이나 문서로 옮긴다. 같은 방식으로 [스킬](/glossary#skills)도 본문이 길어지면 참고 자료로 분리한다.

## 개선 루프 고정

개선은 사람이 매번 기억해야만 일어나지 않는다. 작업이 끝나는 지점에 확인 질문을 남겨 둔다.

```text
이번 작업에서 다음 작업에도 도움이 될 만한 규칙, 절차,
프로젝트 지식, 테스트가 생겼는지 확인해 줘.

- 필요한 경우에만 적절한 Rule, Skill, Docs, ADR, Test, Script를 제안해 줘.
- 일회성 정보나 이미 있는 내용과 중복되는 내용은 제안하지 마.
- 반영은 하지 말고 목록만 보여 줘.
```

승인과 반영을 나누면 검토할 수 있다. 이 요청을 [훅](/harness-advanced/hooks)의 완료 시점에 연결하면 매번 같은 장소를 훑게 된다. 다만 판단이 필요한 변경은 그대로 사람에게 남겨 둔다.

그다음 남은 것은 검증이다. 환경이 바뀌었으면 기존 작업이 같은 결과를 내는지 확인한다. [검증](/harness-advanced/verification) 페이지에서 다루는 순서를 그대로 쓴다. 규칙을 추가하고 테스트를 돌리지 않으면 개선인지 변경인지 알 수 없다.

## 한 번에 하나씩 고친다

여러 개선을 한 번에 넣으면 무엇이 효과가 있었는지 알 수 없다. 다음 순서를 지킨다.

1. 고칠 대상을 하나 고른다.
2. 변경 전 기준을 남긴다. 어떤 명령의 결과가 기준인지 적는다.
3. 한 가지만 고친다.
4. 같은 기준으로 다시 확인한다.
5. 결과와 남은 문제를 적는다.

기준이 없으면 비교할 대상이 없어 개선 여부를 판단할 수 없다. 이때 쓰는 기록은 [문서](/harness-basics/docs)에 남기고, 자주 되돌아오는 오류는 테스트로 고정한다.

## 흔히 빠지는 지점

- **환경을 고치지 않고 매번 다시 설명한다.** 같은 요청을 두 번째 보낸다면 그 자리에는 파일이 있어야 한다.
- **지시를 늘리는데 이유를 적지 않는다.** 나중에 그 규칙이 왜 있는지 확인해야 할 때 이유가 없다.
- **삭제를 미룬다.** 잘못된 지시는 남아 있는 동안 계속 읽힌다.
- **비밀값을 남긴다.** 개선 기록에도 토큰 값을 옮기지 않는다. 기준은 [보안](/harness-basics/security) 페이지에서 확인한다.
- **개선 뒤 검증을 생략한다.** 규칙은 사용량과 판단을 바꾸므로 같은 입력으로 결과를 다시 본다.

::: details 보충: 메모리와 자기 개선의 경계
[런타임별 메모리 안내](https://learn.chatgpt.com/docs/customization/memories)에 정리된 것처럼, 개인 선호와 반복 피드백은 로컬 메모리에 두다가 모두가 알아야 하는 순간 [룰](/glossary#rules)·[스킬](/glossary#skills)·[문서](/harness-basics/docs)로 올린다. 올릴 때는 이유와 함께 옮기고, 옮긴 뒤에는 같은 내용을 두 곳에 남기지 않는다.

이 저장소에서는 기준 파일(AGENTS.md)의 길이 상한을 두고, 넘으면 절차를 스킬로, 지식을 문서로 옮긴다. 옮기는 대상은 절차와 지식이고, 결정 이력은 별도 기록으로 남긴다. [Claude Code 모범 사례](https://code.claude.com/docs/en/best-practices)는 지시 파일을 간결하게 유지하고 코드에서 추론하기 어려운 내용만 적는 방향을 권한다. 정확한 길이 기준은 런타임마다 다르고, 이 저장소의 수치는 자체 기준이다. 기준일: 2026-09-30.
:::