AI 문서화 안내서: 모델 카드부터 평가 보고서와 에이전트 카드까지

AI 요약

전통적인 소프트웨어 문서는 함수와 API처럼 반복 가능한 동작을 설명했습니다. 생성형 AI와 에이전트는 같은 입력에도 결과가 달라지고, 개발자가 미리 정하지 않은 경로로 행동하기도 합니다. 따라서 AI 문서는 정확히 무엇을 할지 단정하기보다 학습 재료와 성능 측정 방법, 허용 범위, 실제 행동 기록을 밝혀야 합니다. 글은 이 문서들을 단순한 서류가 아니라 동료와 사용자, 감사 담당자, 규제 기관이 AI 시스템을 신뢰하도록 돕는 근거로 설명합니다.

모델과 데이터 문서

모델 카드는 모델의 용도와 학습 데이터, 평가 결과, 한계, 사용해서는 안 되는 범위를 정리합니다. 다른 팀에 모델을 전달하거나 모델을 배포할 때, 가중치만으로 알 수 없는 사용 조건을 전달하는 역할을 합니다. 글은 Mitchell 등 연구자의 2019년 제안과 Hugging Face 같은 모델 허브의 활용을 언급하며, EU AI Act에서 고위험 시스템에 모델 카드나 이에 준하는 문서를 요구한다고 설명합니다.

데이터시트는 데이터셋의 출처와 수집 방법, 구성, 알려진 편향, 동의와 라이선스, 적절한 사용 범위를 기록합니다. 데이터의 맥락은 시간이 지나면 만든 사람에게서도 사라지므로, 데이터셋을 다른 사람이 계속 쓰는 상황이라면 작성할 필요가 있습니다. 시스템 카드는 단일 모델을 넘어 여러 모델과 검색, 라우팅 등 구성 요소를 포함한 전체 시스템을 다룹니다. 아키텍처뿐 아니라 안전성 평가와 운영 제약, 배포 맥락도 기록합니다.

평가와 에이전트 문서

평가 보고서(Eval Report)는 테스트 데이터와 평가 방법, 지표에 깔린 가정, 결과를 어느 정도 신뢰할지 설명합니다. 정확도 95%라는 수치만으로는 어떤 데이터와 조건에서 무엇을 정답으로 봤는지 알 수 없습니다. 글은 평가 방법을 공개하지 않은 벤치마크 결과를 근거가 아닌 홍보 주장으로 봐야 한다고 강조합니다. 회귀 평가(Regression Eval)는 모델이나 프롬프트를 바꾼 뒤 기존 동작이 깨졌는지 반복 확인하는 절차를 문서화합니다. 벤치마크 카드는 벤치마크가 실제로 측정하는 항목과 한계를 설명해 순위표의 점수를 과도하게 해석하지 않도록 돕습니다.

에이전트 카드는 역할과 메모리 유형, 도구 연결, 통신 프로토콜, 모니터링 항목, 거버넌스 범위와 평가 지표를 기록하는 2026년 문서 표준으로 소개됩니다. 도구를 호출하거나 데이터를 다루며 무인으로 작동하는 에이전트를 운영·감사하려면 무엇에 접근하고 어떻게 감시하는지 알아야 합니다. 정책 카드는 허용된 행동과 권한을 기계가 읽을 수 있는 형태로 표현해 실행 중에도 적용하는 문서입니다. 에이전트의 권한이 실제 변경이나 삭제, 결제 같은 결과로 이어진다면 사후 설명만으로는 부족합니다. 코딩 에이전트가 읽는 저장소 지침 파일은 프로젝트 규칙과 제약, 아키텍처 설명을 제공하며, 문서 작성과 에이전트 동작 지시가 만나는 유형으로 설명됩니다.

운영 기록과 거버넌스

감사 추적(Audit Trail)은 운영 중 발생한 중요한 모델·에이전트 결정을 변경 불가능한 추가 전용 기록으로 남깁니다. 사고 조사에서 시스템이 실제로 무엇을 했는지 재구성하려면 내구성 있고 변조 흔적을 확인할 수 있는 기록이 필요합니다. 글은 규제·거버넌스 문서로 컴플라이언스 카드와 AI 카드, 특정 배포의 용도와 위험을 정리하는 사용 사례 카드, 시스템의 동작과 한계를 공개하는 투명성 보고서도 소개합니다. EU AI Act와 2026년 1월 출범한 싱가포르의 Model AI Governance Framework for Agentic AI를 사례로 들며, 후자는 위험 평가와 에이전트 권한 제한, 주요 결정 단계의 인간 책임을 요구한다고 설명합니다.

글이 제시하는 네 가지 질문은 ‘무엇으로 학습했는가’, ‘어떻게 측정했는가’, ‘무엇을 하도록 허용했는가’, ‘실제로 무엇을 했는가’입니다. 모델 카드와 데이터시트는 학습 재료를, 평가 보고서는 측정 방법을, 에이전트 카드와 정책 카드는 권한을, 감사 추적은 실제 행동을 설명합니다. 문서가 신뢰를 얻으려면 최신 상태도 유지해야 합니다. 글은 AI 문서가 모델이나 프롬프트 변경 뒤 낡을 수 있으므로, 측정 결과와 설정을 생성 파이프라인에서 함께 만들고 변경 시 갱신하는 방식을 권합니다.

dev.to 반응

• @theagentloop — 네 가지 질문으로 나눈 방식이 맞습니다. 그중 ‘실제로 무엇을 했는가’가 현장에서 답하기 가장 어렵습니다. 모델 카드와 데이터시트는 의도와 입력을 설명하지만, 사고가 난 뒤 제가 찾는 건 어떤 도구를 어떤 인자로 호출했고 비용이 얼마였는지 보여주는 실행 기록입니다. 사전에 작성할 수 없는 기록이며, 시스템 설명이 아니라 실행별 기록이라는 점에서 이 지도의 가장 얇은 부분이기도 합니다. 에이전트 청구서나 사고를 따질 때 비용 합계만으로는 급증이 있었다는 사실만 알 뿐, 무엇을 바꿔야 할지 알 수 없습니다. 그래서 도구별 실행 원장을 별도의 문서 유형으로 다루기 시작했습니다. 팀에서는 어떤 문서를 직접 작성하고 어떤 문서를 생성하나요? 제 추측으로는 모델 카드는 직접 작성하고, 평가 보고서는 절반쯤 자동 생성하며, 에이전트 카드는 그 중간일 듯합니다. 실제 제출을 해 본 분들의 이야기를 듣고 싶습니다.
  • @james_anderson_h — 지도에서 가장 뚜렷한 공백을 짚으셨습니다. 다른 문서는 시스템을 설명하지만 실행 기록만은 사후에 실행별로 남기는 기록이며, 사고 뒤 실제로 찾게 되는 자료입니다. ‘비용 합계만으로는 급증이 있었다는 사실만 알 뿐, 무엇을 바꿔야 할지 알 수 없다’는 지적처럼 도구별 원장은 감사 추적의 각주가 아니라 독립된 문서 유형으로 다뤄야 합니다. 직접 작성하느냐 자동 생성하느냐는 질문에 대한 제 솔직한 생각도 비슷합니다. 모델 카드는 사람만 아는 의도를 담으니 직접 작성하고, 평가 보고서는 수치는 자동화하되 방법론과 주의사항은 사람이 쓰며, 에이전트 카드는 그 중간입니다. 다만 실제로 대규모 제출을 해 본 분들의 이야기를 듣고 싶습니다. 문서가 점점 더 자동 생성되는 쪽으로 기울면서, 문서가 막으려던 신뢰 문제가 다시 생기는지도 궁금합니다.
• @micheypico — heypico.ai에서 모델 32개를 하나의 키로 연결하는 모델 라우팅 계층을 운영하는데, LLM 주변의 결정론적 구조가 다중 모델 구성을 실용적으로 만듭니다. 작업 도중 제공자가 요청을 제한하면 재시도할지, 다른 제공자로 넘길지, 오류를 낼지는 상태 머신이 결정합니다. LLM은 그 판단을 안정적으로 내리지 못합니다. ‘불안정한 에이전트’를 디버깅하다 보면 좋은 모델 주변에 상태 머신이 빠진 문제를 찾는 경우가 많습니다.
  • @james_anderson_h — ‘불안정한 에이전트 디버깅은 대개 좋은 모델 주변에 상태 머신이 빠진 문제를 찾는 일’이라는 말이 요점을 잘 짚습니다. 작업 중 요청 제한이 발생했을 때 재시도와 전환, 오류 중 무엇을 택할지는 결정론적 판단입니다. 그 결정을 LLM에 맡기면 불안정해집니다. 모델이 문제가 아니라 주변 구조가 빠진 게 문제였습니다.
• @contentclips_st — 분류 방식이 좋습니다. 네 가지 질문은 문서를 판별하는 기준이 됩니다. 어떤 문서가 그중 하나에도 연결되지 않는다면 신뢰를 위한 문서가 아닐 가능성이 큽니다. 실제 운영에서 얻은 교훈 하나는 모델 카드와 평가 보고서가 README보다 빨리 낡는다는 점입니다. 재학습이 이뤄지는 순간 손으로 쓴 카드와 실제 모델이 달라집니다. 도움이 된 방법은 문서를 빌드 산출물로 취급하는 것입니다. 모델을 만드는 파이프라인에서 설정과 평가 결과를 넣고 Markdown을 생성하며, 모델 가중치와 함께 커밋합니다. 입력이 바뀌면 CI에서 낡은 문서를 표시합니다. 에이전트 카드의 ‘실제로 무엇을 했는가’도 기억에 의존해 쓰지 말고 실행 로그에서 가져와야 신뢰할 수 있습니다. 신뢰 문서를 손으로 편집하면 목적을 무너뜨립니다.
  • @james_anderson_h — 문서가 낡는 문제를 제가 충분히 다루지 못했습니다. 실제 상태와 달라진 문서는 아예 없는 것보다 나쁩니다. 존재하지 않는 상태를 자신 있게 보증하는데, 관리되는 것처럼 보여 사람들이 믿기 때문입니다. 파이프라인에서 빌드 산출물로 만드는 게 문제를 해결하는 방법입니다. 사람이 손으로 고치는 순간 다시 차이가 벌어집니다.
  • @contentclips_st — 동의합니다. 다만 생성만으로는 소비 시점의 최신성을 보장하지 못합니다. 일정에 맞춰 실행하는 파이프라인의 산출물도 낡은 상태를 자신 있게 보증할 수 있습니다. 실무에서 도움이 되는 방법 두 가지가 있습니다. 생성 문서마다 모델 버전과 평가 데이터셋 해시, 생성 시각을 출처 정보로 기록하면 문서가 전달된 뒤에도 낡았는지 드러납니다. 또 CI에서 문서를 다시 생성해 저장된 결과와 비교하고, 다르면 빌드를 실패시킵니다. 이 차이는 변경 기록 역할도 합니다. 검토자가 겉보기엔 똑같은 보고서를 다시 읽지 않고 무엇이 바뀌었는지 볼 수 있습니다. 손 편집도 조용한 문서 차이가 아니라 빌드 실패로 드러납니다. 그래야 ‘생성하고 손대지 않기’가 마감 앞에서도 유지됩니다.
  • @james_anderson_h — 출처 정보 기록과 CI 최신성 검사가 이 대화에서 빠진 조각입니다. 생성은 차이를 줄여 주지만, 변경 때마다 다시 생성해 비교해야 실제로 강제할 수 있습니다. 손 편집을 조용한 차이에서 빌드 실패로 바꾸는 방법만이 ‘손대지 않기’를 마감 앞에서도 지켜 줍니다. 절제만으로는 유지되지 않습니다. 차이를 변경 기록으로 쓰는 방법도 가져가겠습니다. 검토자가 보고서를 다시 읽는 것보다 무엇이 바뀌었는지 보는 편이 낫습니다.
• @contentclips_st — 차이를 알아차리기 쉽게 하는 또 한 가지 방법은 생성 문서에 소스 커밋 해시와 생성 시각을 넣는 것입니다. 관리되는 듯 보이지만 실제로는 낡은 문서도 검색으로 찾을 수 있습니다. 문서가 자신의 최신 여부를 직접 드러내므로, 손 편집은 기본 상태가 아니라 예외로 보입니다. 생성기에 한 줄 더하면 낡았는지 기계가 답합니다.
  • @james_anderson_h — 소스 커밋 해시를 넣는 방법이 좋습니다. 문서가 자신의 최신 여부를 직접 답하게 하므로, 자신 있게 현재 상태를 보증하는 일을 막고 손 편집도 조용한 기본값이 아니라 눈에 보이는 예외가 됩니다. 생성기에 한 줄을 더하면 신뢰 여부를 검색으로 확인할 수 있습니다.

원문: dev.to / 번역·요약: Trawling