개인이 AI를 잘 쓰는 것과 팀 전체가 AI와 함께 일하는 것은 다른 문제입니다. 한 사람은 구현만 시키고 다른 사람은 테스트와 문서까지 요구합니다. 검토 중인 제안이 확정된 규칙처럼 전달되거나 이미 버린 방법이 다시 제안되기도 합니다. 요즘IT의 이정민 필자는 딥시크가 공개한 딥시크 하네스 저장소에서 이 문제를 다루는 방식을 읽어 냅니다. 딥시크 하네스는 AI 모델이 파일을 읽고 도구를 쓰며 작업하도록 만든 실행 환경입니다. 원문

필자가 주목한 점은 작업자가 바뀌어도 이전 판단을 확인하고 같은 기준에서 일을 이어 가도록 저장소를 구성했다는 점입니다. 별도 llm-wiki에 지식을 모으기보다 코드가 있는 곳에서 규칙과 기록, 절차를 연결하는 쪽이 팀 개발에는 더 간결하다고 봅니다. 다만 공개 저장소만으로 내부 협업의 성과까지 알 수는 없다고 선을 긋습니다.

AGENTS.md로 완료 기준을 맞춘다

AGENTS.md에서 필자가 본 것은 규칙의 양보다 작업 조건과 확인할 자료를 연결한 방식입니다. 패키지를 고치기 전에는 아키텍처 문서를 읽고, 푸시 전에는 dsh-pre-push-checks 로 변경에 맞는 검사를 고릅니다. 글과 주석의 검토 기준은 dsh-prose-standard 로 연결합니다.

협업과 직접 맞닿는 규칙은 세 가지입니다.

  • 중요한 변경에는 같은 PR에서 Agent Note를 추가하거나 갱신해 결정 기록을 남깁니다.
  • 코드가 바뀌면 관련 설명도 함께 고쳐서 다음 작업자가 오래된 문서를 현재 동작으로 오해하지 않게 합니다.
  • 검증 결과는 실제로 실행한 내용만 보고합니다.

요청에 문서나 테스트를 일일이 적지 않아도 저장소 기준이 필요한 기록과 검증을 요구합니다. 어디까지 해야 작업이 끝나는지를 지시하는 사람에게만 맡기지 않는 구조입니다.

지침을 두는 것과 모델에 전달하는 것도 함께 설계했습니다. 딥시크 하네스는 기본 구성에서 작업 위치에 해당하는 AGENTS.md를 모델에 넘기고, 하위 영역을 다룰 때는 그 영역의 지침을 추가로 넘깁니다. 연결된 노트와 스킬까지 자동으로 읽지는 않습니다. 그래서 “새 노트를 쓰기 전에 기존 기록을 검색하라"처럼 자료를 확인할 시점까지 규칙에 적어 둡니다.

노트를 상태별 폴더로 나눈다

.agents/notes 는 개별 기록보다 상태별 폴더가 먼저 보입니다. 폴더 이름이 다음 작업자에게 그 문서를 얼마나 확정된 내용으로 받아들일지 알려 줍니다.

  • proposed: 아직 검토 중인 제안
  • implemented: 실제로 반영한 결정
  • rejected: 검토했지만 채택하지 않은 제안
  • archived: 현재 기준과 구분해 보존하는 과거 기록

상태 폴더 안은 architecture, process, testing처럼 주제로 다시 나눕니다. 중앙 인덱스를 없앤 기록은 .agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.md 에 있습니다. 경로만 봐도 이미 반영한 결정이고 개발 절차에 관한 내용이라는 것을 알 수 있습니다.

상태를 바꿀 때의 규칙이 더 중요합니다. 제안을 구현했다면 폴더만 옮기지 않고 “앞으로 무엇을 하겠다"는 설명을 “무엇을 결정했다"로 고칩니다. 코드 경로나 기본값이 바뀌면 관련 사실도 갱신합니다. 결정을 뒤집을 때는 기존 문서를 반대 내용으로 고쳐 쓰지 않습니다. 새 노트를 만들고 이전 기록과 연결해서 왜 선택이 바뀌었는지 남깁니다.

판단 근거를 남긴 중앙 인덱스 제거

중앙 인덱스 제거 노트에는 지금의 폴더 구조를 택한 이유가 담겨 있습니다. 각자 다른 노트를 쓰더라도 공통 목록 파일을 함께 고치면 서로 관련 없는 작업끼리 충돌이 납니다. 기록에는 인덱스를 계속 자동 생성하는 방법, 필요할 때만 생성하는 방법, 손으로 관리하는 방법을 검토한 흔적이 있습니다. 최종 결정은 별도 인덱스 없이 상태별·주제별 폴더와 저장소 검색을 쓰는 것이었습니다.

필자는 여기서 얻을 힌트가 “인덱스를 만들지 말라"가 아니라고 말합니다. 독립된 작업이 같은 파일을 불필요하게 건드리지 않게 하고 그 선택의 이유를 남겼다는 점이 핵심입니다. 새 팀원이나 에이전트가 “목록이 있으면 더 편하지 않을까?” 하고 생각해도 이전 대화에 참여한 사람을 찾지 않고 이유를 확인할 수 있습니다.

스킬에 팀의 판단 기준을 담는다

딥시크 하네스의 팀 공용 스킬에는 리뷰와 문서 작성뿐 아니라 기록 정리, 중복 제안 병합, 서로 의존하는 변경 반영 절차까지 들어 있습니다.

기록 정리(dsh-archive-agent-notes) 는 문서의 나이나 길이가 아니라 앞으로의 판단에 도움이 되는지를 봅니다. 구현이 끝났어도 중요한 대안이나 보안 제약이 담겨 있으면 남깁니다. 검토 중인 제안은 보관하지 않고, 더 추진하지 않기로 했다면 이유를 적어 거절합니다. 정리한 문서 개수를 목표로 삼지 못하게 하고 기준을 적용하기 어려운 사례는 인계할 때 따로 보고하게 합니다.

개선 후보 찾기(dsh-find-simplifications) 는 제안을 많이 만들기보다 근거가 분명한 소수의 후보를 찾게 합니다. 다른 PR의 제안을 가져올 때는 같은 주제를 다룬 제안을 기존 노트에 합치고, 개수를 채우려고 중복되거나 근거가 약한 제안을 가져오지 말라고 적어 둡니다. 중복 PR을 닫는 일은 사용자 요청이나 명확한 정리 책임이 있을 때만 합니다.

연결된 PR 반영(dsh-merging-stacked-prs) 은 서로 의존하는 PR을 순서대로 반영할 때 씁니다. 명령어보다 자동으로 진행해도 되는 범위가 눈에 띕니다. PR 작성자가 서로 다르거나 확인할 수 없으면 먼저 사용자에게 묻습니다. 맨 위 PR이 준비됐다고 아래 PR까지 준비됐다고 보지 않고, 다른 열린 PR이 의존하는 브랜치는 삭제하지 않습니다.

리뷰는 이전 결정을 그대로 따르는 절차가 아니다

dsh-code-review 는 코드와 함께 공통 규칙, 테스트 정책, 관련 Agent Notes를 확인하게 합니다. 그러면서도 이전 노트와 의견이 다르다는 이유만으로 변경을 거절하지 말라고 안내합니다. 기존 결정은 판단의 출발점이고, 새 근거가 있으면 다시 논의할 수 있습니다. 대신 이전 선택의 이유를 확인하고 무엇이 달라졌는지 설명해야 합니다.

검증에서도 작업자의 보고와 실제 근거를 구분합니다. 테스트가 구현을 그대로 되풀이하는지, 막으려는 오류가 생기면 정말 실패하는지 살핍니다. 번역 문서가 자동 검사를 통과했다고 의미까지 같다고 보지 않습니다.

필자는 마지막으로 잘 쓰이는 스킬을 팀 공통 절차로 채택할 때도 같은 관점이 필요하다고 말합니다. 누군가에게 유용했다는 이유만으로 공유하지 말고 어떤 작업에 도움이 됐는지, 기존 규칙과 충돌하지 않는지, 다른 팀원도 같은 기준으로 쓸 수 있는지 함께 검토해야 한다는 것입니다.

요약

  • 딥시크 하네스는 AGENTS.md에 결정 기록, 문서 갱신, 실제 검증 보고를 완료 기준으로 적어 둡니다.
  • 노트는 proposed, implemented, rejected, archived 상태 폴더로 나누고, 결정을 뒤집을 때는 새 노트를 만들어 이전 기록과 연결합니다.
  • 중앙 인덱스를 없앤 이유처럼 채택하지 않은 대안과 그 근거까지 남깁니다.
  • 기록 정리, 개선 제안, 연결된 PR 반영, 코드 리뷰를 팀 공용 스킬로 두고 자동으로 해도 되는 범위를 정해 둡니다.