화면 모드
하네스 스스로 개선하기
룰과 스킬을 한 번 만들어 끝내면 다음 작업은 같은 시행착오를 반복한다. 개선의 대상은 만들어진 파일만이 아니다. 에이전트가 일하는 환경 자체다. 실패와 반복이 남을 때마다 무엇을 고칠지 정해 두면 환경이 따라온다.
기준일: 2026-09-30
만들고 끝내지 않는 루프
작업은 대체로 이 순서를 반복한다.
해결이 곧 끝이 아니다. 같은 문제가 다시 나오면 그건 한 번의 일이 아니라 환경의 문제로 본다. 반대로 한 번뿐인 일은 환경에 넣지 않는다. 남길수록 읽는 사람이 줄어들고, 나중에는 무엇을 지웠는지 알 수 없다.
기록할 위치와 내용
남길 대상을 정해 두지 않으면 같은 내용이 여러 곳에 흩어진다. 판단 기준은 짧게 세 가지다. 항상 필요한가, 반복되는가, 팀이 알아야 하는가.
| 남길 내용 | 남기는 곳 | 예 |
|---|---|---|
| 항상 필요한 짧은 규칙 | 룰 | pnpm만 사용한다 |
| 반복되는 작업 절차 | 스킬 | REST API를 만드는 순서 |
| 개인 선호와 피드백 | 메모리 | 말투와 코드 스타일 |
| 프로젝트 지식 | 문서 | 빌드 명령과 배포 대상 |
| 중요한 결정 | 문서의 기록 | 결제 제공자 선정 |
| 다시 하면 안 되는 오류 | 테스트·린트 | 파서 버그 재발 방지 |
| 반복되는 정해진 작업 | 스크립트 | 파일 일괄 변환 |
| 특정 시점 자동 실행 | 훅 | 편집 뒤 포맷 실행 |
왼쪽 열이 옆에 있으면 왼쪽에 남긴다. 개인 취향이 문서에 있으면 문서가 제안처럼 읽히고, 반드시 지킬 규칙이 개인 기억에만 있으면 다른 사람이 볼 때 빠진다. 판단이 애매하면 메모리 페이지를 다시 본다.
자동화와 확인의 구분
환경을 고치는 일은 대부분 자동화할 수 있지만, 전부를 자동화하면 원인을 잃는다. 판단의 무게에 따라 나눈다.
| 대상 | 처리 방식 |
|---|---|
| 관례 보강 | 자동 |
| 테스트 추가 | 자동 |
| 문서 갱신 | 자동 |
| 배포 정책 변경 | 사람 확인 |
| 보안 정책 변경 | 사람 확인 |
| 권한 범위 확대 | 사람 확인 |
에이전트에게 반복 규칙을 추가하라고 요청해 규칙이 늘어나는 것은 괜찮다. 하지만 권한이나 배포를 넓히는 요청은 별도로 검토한다. 같은 요청 안에 섞어 두면 넓히는 부분까지 함께 처리된다. 이 구분은 보안 페이지의 원칙과 같은 방향이다.
추가와 정리
환경을 개선할 때 빠지기 쉬운 동작이 있다. 잘못된 내용을 계속 쌓는 것이다. 그래서 네 가지 동작을 함께 쓴다.
| 동작 | 언제 |
|---|---|
| 추가 | 새 상황이 생겼을 때 |
| 갱신 | 기존 항목이 틀렸을 때 |
| 통합 | 두 곳에 흩어진 내용을 한곳으로 |
| 제거 | 더 이상 필요 없는 내용 |
제거가 빠지면 파일이 부풀어 읽는 비용만 든다. 파일을 줄이는 것도 개선이다. 이 저장소는 룰 파일의 길이를 정해 두고, 그 수치를 넘으면 내용을 스킬이나 문서로 옮긴다. 같은 방식으로 스킬도 본문이 길어지면 참고 자료로 분리한다.
개선 루프 고정
개선은 사람이 매번 기억해야만 일어나지 않는다. 작업이 끝나는 지점에 확인 질문을 남겨 둔다.
text
이번 작업에서 다음 작업에도 도움이 될 만한 규칙, 절차,
프로젝트 지식, 테스트가 생겼는지 확인해 줘.
- 필요한 경우에만 적절한 Rule, Skill, Docs, ADR, Test, Script를 제안해 줘.
- 일회성 정보나 이미 있는 내용과 중복되는 내용은 제안하지 마.
- 반영은 하지 말고 목록만 보여 줘.승인과 반영을 나누면 검토할 수 있다. 이 요청을 훅의 완료 시점에 연결하면 매번 같은 장소를 훑게 된다. 다만 판단이 필요한 변경은 그대로 사람에게 남겨 둔다.
그다음 남은 것은 검증이다. 환경이 바뀌었으면 기존 작업이 같은 결과를 내는지 확인한다. 검증 페이지에서 다루는 순서를 그대로 쓴다. 규칙을 추가하고 테스트를 돌리지 않으면 개선인지 변경인지 알 수 없다.
한 번에 하나씩 고친다
여러 개선을 한 번에 넣으면 무엇이 효과가 있었는지 알 수 없다. 다음 순서를 지킨다.
- 고칠 대상을 하나 고른다.
- 변경 전 기준을 남긴다. 어떤 명령의 결과가 기준인지 적는다.
- 한 가지만 고친다.
- 같은 기준으로 다시 확인한다.
- 결과와 남은 문제를 적는다.
기준이 없으면 비교할 대상이 없어 개선 여부를 판단할 수 없다. 이때 쓰는 기록은 문서에 남기고, 자주 되돌아오는 오류는 테스트로 고정한다.
흔히 빠지는 지점
- 환경을 고치지 않고 매번 다시 설명한다. 같은 요청을 두 번째 보낸다면 그 자리에는 파일이 있어야 한다.
- 지시를 늘리는데 이유를 적지 않는다. 나중에 그 규칙이 왜 있는지 확인해야 할 때 이유가 없다.
- 삭제를 미룬다. 잘못된 지시는 남아 있는 동안 계속 읽힌다.
- 비밀값을 남긴다. 개선 기록에도 토큰 값을 옮기지 않는다. 기준은 보안 페이지에서 확인한다.
- 개선 뒤 검증을 생략한다. 규칙은 사용량과 판단을 바꾸므로 같은 입력으로 결과를 다시 본다.
보충: 메모리와 자기 개선의 경계
런타임별 메모리 안내에 정리된 것처럼, 개인 선호와 반복 피드백은 로컬 메모리에 두다가 모두가 알아야 하는 순간 룰·스킬·문서로 올린다. 올릴 때는 이유와 함께 옮기고, 옮긴 뒤에는 같은 내용을 두 곳에 남기지 않는다.
이 저장소에서는 기준 파일(AGENTS.md)의 길이 상한을 두고, 넘으면 절차를 스킬로, 지식을 문서로 옮긴다. 옮기는 대상은 절차와 지식이고, 결정 이력은 별도 기록으로 남긴다. Claude Code 모범 사례는 지시 파일을 간결하게 유지하고 코드에서 추론하기 어려운 내용만 적는 방향을 권한다. 정확한 길이 기준은 런타임마다 다르고, 이 저장소의 수치는 자체 기준이다. 기준일: 2026-09-30.