발표에서 확인된 핵심 사실

번역체와 의미 없는 반복 문장이 섞인 문서 관리의 한계를 해결하기 위해 마크다운 테이블과 고정 템플릿을 제거한 docs-system(AI 에이전트 작업 지시 리서치 및 설정 저장소)을 공개했다. 표를 제거함으로써 가독성 저하와 수정의 어려움을 해결하고 필요한 정보의 유무와 필수적인 역할 정의에 집중하는 구조를 만들었다. 문서의 시각적 모양을 맞추는 작업보다 정보의 실질적 포함 여부를 판별하는 것이 더 중요하다는 판단에 따른 결과다.

해당 레포지토리는 AI 에이전트에게 작업을 지시하는 방법론을 리서치하고 문서와 스킬을 세팅하는 용도로 사용된다. 모든 저장소에 일괄적으로 적용하는 프레임워크나 완성된 형태의 애플리케이션이 아니다. 사용자가 관리하는 각 저장소의 성격과 목적에 맞게 내용을 고쳐 쓸 수 있도록 구성했다.

함께 제시된 use-design-docs(문서 작성 가이드)는 표 없이도 비교 순서와 논리적 근거를 명확히 따라갈 수 있는 작성법을 지향한다. 고정된 템플릿 대신 내용에 따라 소제목과 짧은 문단, 목록을 선택적으로 사용하여 가독성을 확보했다. 문서의 외형적 완성도보다 각 문서가 수행해야 할 필수적인 역할을 정의하는 기능적 측면에 우선순위를 둔다.

기술이 실제로 작동하는 방식

AI 에이전트는 docs/designs/README.md 파일을 읽어 요구사항과 리서치 자료, 결정 및 계획을 분리해 기록한다. use-design-docs(설계 문서 활용 스킬)는 작업자가 요청한 작업 내용과 완료 조건을 요구사항으로 정의하고, 외부 자료에서 확인한 사실이나 AI의 분석 및 제안은 별도 문서로 관리하도록 지시한다. 특히 결정이 필요한 내용은 승인 전까지 제안 상태로 유지하며, 최종 실행 계획에는 해결된 요구사항과 확정된 결정 사항만을 반영한다. 정보의 성격에 따라 기록 위치를 강제해 분석 데이터가 실행 지침으로 오인되는 상황을 방지한다.

스크립트가 번역체 가능성이 높은 표현과 지나치게 긴 문단을 먼저 추출해 후보군을 제시하면 에이전트가 이를 검토한다. use-words-review(문장 검토 스킬)는 작성, 커밋, 게시 또는 외부 공유를 앞둔 한국어 문서를 대상으로 작동한다. 서브에이전트나 메인 에이전트는 후보 문장을 읽어야 하는 당사자와 표현이 사용된 경위, 문장 사이의 관계를 분석해 자연스러운 한국어 표현인지 확인한다. 기계적인 패턴 추출 이후 문맥 검토를 거치는 2단계 프로세스를 통해 문서의 가독성을 확보한다.

확인해야 할 핵심 지점

토큰 소모량과 호출 횟수를 낮추기 위해 일반 채팅과 진행 알림을 검토 대상에서 제외했다. 초기에는 중요 채팅 답변까지 모두 검토 범위에 포함했으나 이로 인해 API 호출 횟수가 과도하게 증가하고 토큰 소모량이 높아지는 결과가 나타났다. 현재는 저장하거나 공유할 결과물 전체를 대상으로 한 번만 검토하도록 범위를 한정해 리소스 낭비를 막았다. 불필요한 호출을 줄여 운영 비용의 효율성을 확보하고 실무 환경에서의 적용 가능성을 높였다.

에이전트가 스크립트가 찾지 못한 문장의 의미 문제까지 정밀하게 분석하지만 텍스트를 자동으로 수정하는 기능은 제공하지 않는다. use-words-review(문장 검토 도구)는 분석된 검토 결과만을 사용자에게 전달하며 실제 수정은 별도의 작업으로 진행하도록 설계되었다. 사용자가 에이전트가 찾아낸 의미상의 오류나 검토 내용을 확인한 뒤 직접 수정 작업을 거쳐 최종안을 완성하는 방식이다. AI의 임의 수정으로 인한 맥락 훼손을 원천 차단하고 작업자의 최종 결정권을 보장한다.

정보의 역할이 요구사항인지 제안인지에 따라 문서를 분리해 관리하며 템플릿 강박을 배제하는 실무 기준을 적용해야 한다.