AI 네이티브 팀은 저장소에 뭘 남길까? 딥시크 하네스 분석

개인이 AI를 잘 쓰는 것과 팀 전체가 AI와 함께 일하는 것은 다른 문제입니다. 한 사람은 구현만 요청하고, 다른 사람은 테스트와 문서까지 요구합니다. 검토 중인 제안을 확정된 규칙처럼 전달하거나, 이미 채택하지 않기로 한 방법을 다시 제안할 수도 있습니다. 지시하는 사람이 바뀔 때마다 배경과 기준을 다시 설명해야 한다면, 협업은 여전히 개인의 기억에 의존하게 됩니다.

딥시크(DeepSeek)가 공개한 딥시크 하네스(DeepSeek Harness)에서는 이 문제를 다루는 방식을 엿볼 수 있습니다. AI 모델이 파일을 읽고 도구를 사용하며 작업하도록 만든 실행 환경인데요. 그 저장소에는 개발 규칙뿐 아니라 결정의 근거와 반복 작업의 절차가 함께 관리되고 있습니다. AI 네이티브 조직의 협업을 이해하는 데 흥미로운 사례입니다.

눈여겨 볼 부분은 작업자가 바뀌어도 이전 판단을 확인하고 같은 기준에서 일을 이어가도록 구성했다는 점입니다. 별도의 llm-wiki에 지식을 모으는 방식보다, 코드가 있는 곳에서 규칙과 기록, 절차를 연결하는 쪽이 팀 개발에는 더 간결한 접근으로 보였습니다. 정보를 많이 쌓기보다 지금 유효한 기준을 구분하고 필요한 순간에 찾아 쓰게 하는 방식입니다.

공개 저장소만으로 내부 협업의 성과까지 알 수는 없습니다. 다만 공통 규칙을 확인하고, 결정 기록을 갱신하며, 다른 작업자의 변경을 검토하는 흐름은 구체적으로 살펴볼 수 있습니다.

지시하는 사람이 달라도 완료 기준은 같아야 한다

딥시크 하네스의 AGENTS.md에서 눈여겨볼 점은 규칙의 양보다 작업 조건과 확인할 자료를 연결한 방식입니다. 패키지를 수정하기 전에는 아키텍처 문서를 읽고, 푸시 전에는 dsh-pre-push-checks로 변경에 맞는 검사를 고르도록 합니다. 글과 주석의 검토 기준은 dsh-prose-standard로 연결합니다.

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

• 중요한 변경에는 결정 기록도 남깁니다. 같은 PR에서 Agent Note를 추가하거나 갱신해야 합니다.
• 코드가 바뀌면 관련 설명도 함께 고칩니다. 다음 작업자가 오래된 문서를 현재 동작으로 오해하지 않도록 합니다.
• 검증 결과는 실제 수행한 내용만 보고합니다. 검사를 했다는 말이 아니라, 무엇을 실행했는지 확인할 수 있어야 합니다.

이 규칙은 에이전트에 일을 시키는 사람들 사이의 차이를 줄이는 데 의미가 있습니다. 요청에 문서나 테스트를 일일이 적지 않았더라도, 저장소의 기준은 변경에 필요한 기록과 검증을 요구합니다. 어디까지 해야 작업이 끝나는지를 개인의 지시에만 맡기지 않는 것이죠.

하위 지침도 작업에 필요한 절차로 연결됩니다. notes/AGENTS.md는 새 기록이 기존 결정을 완전히 대체하는지 일부만 바꾸는지 확인하도록 하고, 구체적인 판단에는 dsh-archive-agent-notes를 사용하게 합니다. 지침에서 요구한 일을 스킬의 절차로 이어가는 구성입니다.

지침을 두는 것과 전달하는 것을 함께 설계한다

규칙을 파일에 적는 것만으로 에이전트가 이를 확인했다고 볼 수는 없습니다. 딥시크 하네스는 기본 구성에서 작업 위치에 해당하는 AGENTS.md를 모델에 전달합니다. 기본 파일 도구로 하위 영역을 다룰 때는 그 영역에 해당하는 지침을 추가로 전달합니다.

다만 연결된 노트와 스킬까지 모두 자동으로 읽는 것은 아닙니다. 지침이 관련 자료를 찾도록 안내하고, 에이전트가 필요한 내용을 확인해야 합니다. 그래서 새 노트를 쓰기 전에 기존 기록을 검색하라는 규칙처럼, 자료를 확인해야 하는 시점까지 정해 둔 것이 중요합니다.

검토 중인 생각과 팀이 채택한 결정을 구분한다

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을 닫는 일도 사용자 요청이나 명확한 정리 책임이 있을 때만 하도록 제한합니다.

여러 에이전트에 개선점을 찾게 하면 비슷한 제안이 쌓일 수 있습니다. 이 스킬은 결과물을 모두 더하는 대신, 무엇이 새로운 기여이고 무엇이 이미 논의 중인 내용인지 구분하는 기준을 둡니다.

다른 사람의 변경을 다룰 때는 먼저 확인한다

dsh-merging-stacked-prs는 서로 의존하는 여러 PR을 순서대로 반영할 때 쓰는 스킬인데요. 앞선 변경이 반영돼야 다음 변경도 성립하는 상황을 다룹니다.

명령어보다 주목할 부분은 자동으로 진행해도 되는 범위입니다. 연결할 PR의 작성자가 서로 다르거나 작성자를 확인할 수 없다면 먼저 사용자에게 물어보도록 합니다. 기존 연결 순서가 예상과 다를 때도 임의로 재구성하지 않습니다.

또 가장 위의 PR이 준비됐다고 해서 그 아래 변경까지 준비됐다고 판단하지 않습니다. 각 PR의 리뷰와 검사 상태를 따로 확인하고, 다른 열린 PR이 여전히 의존하는 브랜치는 삭제하지 않도록 합니다.

자신에게 맡겨진 작업을 끝내는 것과 다른 작업자의 진행 중인 변경을 건드리는 것은 다른 문제입니다. 이 스킬은 그 차이를 절차에 담고 있습니다.

리뷰는 이전 결정을 맹목적으로 따르는 절차가 아니다

dsh-code-review는 코드뿐 아니라 공통 규칙, 테스트 정책, 관련 Agent Notes를 함께 확인하도록 합니다. 그렇다고 이전 노트와 의견이 다르다는 이유만으로 변경을 거절하지는 말라고 안내합니다.

기존 결정은 판단의 출발점이지 바꿀 수 없는 정답은 아니라는 뜻입니다. 새로운 요구나 근거가 있다면 다시 논의할 수 있습니다. 다만 이전 선택의 이유를 확인하고, 무엇이 달라졌는지 설명해야 합니다.

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

각 단계가 요구하는 내용을 연결하면 작업 흐름은 다음과 같습니다.

• 공통 규칙에서 작업의 기준을 확인합니다.
• 관련 노트에서 이전 판단과 검토한 대안을 찾습니다.
• 해당 스킬로 작업을 수행하고, 필요한 기록과 검증 근거를 남깁니다.
• 리뷰에서 구현과 근거를 확인하고, 필요하면 기존 결정도 다시 논의합니다.

공통 기준은 논의를 생략하기 위한 것이 아닙니다. 서로 다른 작업자가 무엇을 근거로 판단했는지 확인하고, 의견이 다를 때도 같은 자료를 놓고 검토할 수 있게 하는 출발점입니다.

마치며

AI 활용은 결국 컨텍스트 싸움입니다. 팀으로 일할 때의 컨텍스트에는 코드와 문서뿐 아니라, 무엇을 함께 지키기로 했고 어떤 결정을 반영했으며 무엇을 채택하지 않았는지도 포함됩니다.

딥시크 하네스는 그 컨텍스트를 개인의 대화에만 맡기지 않습니다. 결정의 상태를 구분하고, 기록을 유지하거나 정리할 조건을 정하며, 다른 작업자의 변경에 손대기 전에 확인할 절차를 둡니다. 정보를 공유하는 데서 더 나아가, 그 정보를 다루는 방식도 공유하는 것입니다.

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

지시하는 사람마다 모든 배경을 다시 설명하는 대신, 팀이 합의한 기준을 함께 관리하고 작업 중에 찾아 쓰게 하는 것. 딥시크 하네스의 저장소는 AI 네이티브 협업이 더 긴 프롬프트보다 함께 유지하는 판단의 기준에서 시작될 수 있음을 보여줍니다.

<참고>

1. 딥시크 하네스

2. 저장소 공통 규칙

3. 노트 작성자 규칙

4. 지침 전달 방식

5. 노트 작성 규칙

6. 반영된 결정의 관리 규칙

7. 중앙 인덱스를 없앤 결정

8. 노트 정리 스킬

9. 개선 후보를 찾는 스킬

10. 연결된 PR을 반영하는 스킬

11. 리뷰 스킬

요즘IT에서 AI 고수들의 ‘로컬앱 자랑대회’를 엽니다.

오늘(10/6) 저녁 7시. 온라인, 오프라인 동시 진행

➡️ 요즘IT 빌더나잇 온라인 신청하러 가기

ⓒ요즘IT의 모든 콘텐츠는 저작권법의 보호를 받는 바, 무단 전재와 복사, 배포 등을 금합니다.