AI 작업 규칙 공유와 하네스 정리

AI 도구를 바꿀 때마다 코딩 규칙과 작업 순서를 다시 설명하고 있었습니다. 처음에는 로컬 문서를 모아 별도 저장소를 만들고 공통 규칙, 도구별 설정, 템플릿을 정리했습니다.

이후에는 규칙을 공유하는 일과 별도의 실행 체계를 유지하는 일을 나눠 봤습니다. 공통 문서는 계속 필요했지만, 도구가 이미 제공하는 기능 위에 비슷한 실행 구성을 계속 추가할 필요는 없었습니다. 이 글에서는 문서 역할을 나눈 방식과 중복 구성을 줄인 과정을 정리합니다.

작업 규칙과 절차 분리

명명과 테스트, 오류 처리, 로그, API 설계 같은 기준은 공통 문서에 뒀습니다. 프로젝트의 실행 방법과 예외는 해당 저장소에 남기고, 반복 작업의 순서는 별도 절차나 템플릿으로 구분했습니다.

작업할 때마다 모든 문서를 한꺼번에 읽게 하기보다 필요한 문서를 찾을 수 있게 경로와 역할을 정리했습니다. 공통 기준을 바꿀 때 프로젝트마다 같은 문장을 따로 수정하지 않도록 원문을 구분하는 것도 필요했습니다.

복사할 양식과 참조할 원문

규칙을 여러 저장소에 복사하면 원문을 고쳐도 사본은 그대로 남습니다. 반대로 모든 내용을 링크로만 두면 도구가 링크를 읽지 않고 작업을 시작할 수 있습니다. 그래서 공통 기준은 원문으로 연결하되 해당 작업 전에 읽으라는 지시를 함께 둡니다.

공개한 project-guidelines 에는 guidelines/와 templates/를 나눴습니다. 전자는 판단 기준이고 후자는 프로젝트에 가져가 사용하는 양식입니다. 복사한 PR 템플릿은 프로젝트 파일이 되므로 원문 변경이 자동으로 전파되지는 않습니다.

project-guidelines/
  guidelines/
    readme.md
    commit-messages.md
    pull-requests.md
    code-review.md
    releases.md
  templates/
    README.md
    agent-instructions.md
    RELEASE_NOTES.md

이 구조는 코딩·설계·테스트 규칙을 담는 별도 문서의 역할과도 구분했습니다. README 작성 기준은 공개 프로젝트 지침에 두고, 도구별 실행 방식이나 프로젝트 명령은 그에 맞는 문서에 남겼습니다. 하나의 큰 문서에서 모든 내용을 동시에 수정하는 대신 변경할 원문을 찾을 수 있게 했습니다.

다음은 연결 방식의 예시입니다. 같은 내용의 규칙 본문을 다시 적지 않고 관련 작업의 원문을 읽도록 합니다.

- README 작성 전 공통 README 지침을 읽는다.
- 커밋·PR 작성 전 각각의 공통 지침을 읽는다.
- 사용자 요청과 프로젝트의 명시적 규칙을 우선한다.
- 프로젝트의 설치·검증 명령은 해당 저장소 문서를 따른다.

실제 URL이 있는 양식은 에이전트 지침 템플릿 에 있습니다. 특정 시점의 기준으로 재현해야 한다면 main 대신 확인한 커밋을 가리킬 수 있습니다. 반대로 항상 최신 지침을 따르려는 경우에는 변경 내용을 검토할 절차가 필요합니다.

규칙 적용을 확인하는 예시

문서를 연결했다고 도구가 실제로 따랐다는 뜻은 아닙니다. 리뷰에서는 문서 개수보다 결과물에 필요한 내용이 있는지 봤습니다.

초기 매니페스트에는 자동 리뷰·테스트 생성 같은 계획도 있었지만 문서의 로드맵을 구현된 기능으로 쓰지는 않았습니다. 공통 지침을 정리한 결과와 별도 자동 실행 체계를 만든 결과를 구분해야 도구를 바꿔도 남길 부분을 고르기 쉽습니다.

팀에서 쓸 수 있는 예시

팀에 공유할 때는 소개 자료 외에 복사해서 시작할 수 있는 Rules와 Skills, 역할별 템플릿을 남기려 했습니다. 어떤 입력을 받고 무엇을 확인해야 하는지도 함께 적었습니다.

템플릿을 만드는 것과 팀에서 실제로 사용하는 것은 별개의 문제입니다. 이 기록에서 정리할 수 있는 것은 공유할 문서와 예시를 준비한 범위입니다. 사용률이나 생산성 개선을 확인한 통계는 따로 없습니다.

별도 하네스 대신 기본 기능 활용

초기에는 스킬과 에이전트 실행 구성을 별도로 넓히려는 계획도 있었습니다. 이후 공통 관리 경로를 ~/.agents로 모으고 중복되는 하네스를 정리했습니다. 도구가 기본으로 제공하는 기능을 활용하는 방향으로 바꾼 것입니다.

규칙과 실행 구성이 함께 늘어나면 지침을 바꾸려던 작업이 실행 도구를 관리하는 일로 커집니다. 공통 문서는 유지하되 실행까지 별도로 감싸야 하는지 다시 보는 것이 필요했습니다.

초기 저장소를 만든 시점과 이후 정리한 구성도 구분했습니다. 현재 방식만 남기면 처음에 별도 실행 구성을 만들려 했던 이유와 나중에 줄인 이유를 찾기 어려워집니다.

README와 Git 작업 기준

공통 프로젝트 지침에는 README와 아키텍처, 커밋, PR, 리뷰, 릴리스 기준을 뒀습니다. 프로젝트 README는 작업 일지를 늘어놓기보다 기능과 설치·사용 방법을 먼저 보여주도록 고쳤습니다.

개인 경로와 내부 운영값은 별도 문서로 옮기고 프로젝트 구조를 이해하는 데 필요한 설명은 남겼습니다. 병합한 브랜치를 정리할 때도 미병합 작업과 미커밋 파일은 별도로 보존했습니다.

현재는 규칙 개수를 늘리는 것보다 공통 원문과 프로젝트별 차이가 어디에 있는지 구분하는 데 집중하고 있습니다. 문서에 적힌 계획과 실제 적용한 구성도 나눠 관리합니다.