일하는 ai

13. AI한테 설명서 줬더니

7 min read

-

AI에게 문서를 많이 주면 성능이 좋아질 것 같지만, 실제로는 반대가 되는 경우가 자주 있습니다. 이 영상의 핵심은 “정보량”이 아니라 “정확한 정보 선택”입니다.

설명서를 길게 붙이는 방식은 초반엔 안심이 되지만, 운영 단계에서는 중복 읽기·우선순위 혼선·재작업 증가로 바로 비용이 올라갑니다.

안내: 이 문서는 YouTube 영상을 생성형 AI로 구조화해 정리했고, 제품 동작/운영 원칙은 공식 문서를 함께 확인해 반영했습니다.

flowchart LR
A[문제 인지: 설명서를 길게 붙였는데 성능 하락] --> B[원인 분해: 중복 컨텍스트/우선순위 혼선]
B --> C[대응 선택: 핵심 규칙만 남기고 구조 재설계]
C --> D[실행/검증: 짧은 문서 + 반복 측정]

🧠 칠판 치트시트

  • AI는 “많이”보다 “정확히” 알려줄 때 잘 움직인다
  • 문서 길이보다 실패 재현/복구 루틴이 성능을 좌우한다
  • 자동 생성 문서는 초안일 뿐, 그대로 운영 문서가 되면 안 된다
  • 팀 규칙은 짧고 강하게, 작업별 규칙은 분리해서 관리한다

영상 핵심 요약

  • 설명서 자동생성 자체가 문제라기보다, 중복된 상시 컨텍스트가 문제다.
  • 긴 문서는 모델의 집중 지점을 흐리게 만들어, 중요한 제약을 놓치게 한다.
  • 실무에서는 “핵심 규칙 압축 + 작업별 분리”가 더 안정적이다.
  • 좋은 운영은 문서 추가가 아니라 검증 루프 설계에서 나온다.

실무에서 바로 건질 포인트

1) 왜 길수록 망가질까: 컨텍스트 과부하

문서가 길어지면 모델이 더 똑똑해지는 게 아니라, 덜 중요한 문장을 더 많이 읽습니다. 그 결과 꼭 지켜야 할 제약(금지 작업/검증 조건)이 묻히기 시작합니다.

실행 흐름:

  1. 상시 문서에서 “코드로 확인 가능한 설명”을 먼저 제거한다.
  2. 반드시 지켜야 할 규칙(금지/검증/복구)만 남긴다.
  3. 나머지는 작업별 문서로 분리한다.

실무 참고:

2) 자동 생성 설명서는 “초안”으로만 써야 한다

자동 생성된 AGENTS/CLAUDE 계열 문서는 시작점으로는 좋지만, 그대로 운영 기준이 되면 현장 맥락과 충돌이 생깁니다.

실행 흐름:

  1. 자동 생성 결과에서 팀 공통 제약만 추린다.
  2. 프로젝트 고유 정보(금지 파일, 테스트 명령, 배포 경계)만 수동 보강한다.
  3. 일주일 단위로 실제 실패 케이스를 반영해 다듬는다.

실무 참고:

3) 영상에서 제시한 3가지 운영 원칙

영상 후반의 핵심 정리는 세 가지입니다.

  • 첫째: AI가 스스로 파악 가능한 정보까지 다 넣지 말고, 사람이 알려줘야만 아는 맥락만 남긴다.
  • 둘째: 자동화 문서를 그대로 신뢰하지 말고, 실패 조건 중심으로 재정리한다.
  • 셋째: 설명이 계속 길어져야만 동작한다면 문서 문제가 아니라 시스템 구조 문제일 수 있다.

실무 참고:

20분 도입 루틴

  • 5분: 현재 상시 문서에서 중복 설명 5줄 삭제
  • 5분: 금지/검증/복구 규칙만 따로 추출
  • 5분: 최근 실패 1건을 기준으로 체크리스트 3줄 추가
  • 5분: 같은 작업 2회 실행해 재작업 횟수 비교

근거 타임스탬프

  • 0:00 — 설명서를 줬는데 성능이 떨어지는 문제 제기
  • 1:07 — AGENTS.md / CLAUDE.md 개념 정리
  • 2:37 — 스위스 연구팀 실험 결과 소개
  • 4:08 — 실험 설계/해석 포인트
  • 5:44 — 실제 적용 방식 제시
  • 7:58 — 핵심 정리 및 실전 팁

오해 줄이는 한 줄

  • 문서를 줄인다고 품질이 자동으로 올라가진 않습니다. 핵심은 “짧게”가 아니라 “검증 가능한 규칙”으로 바꾸는 데 있습니다.

다음 읽기

영상 메타

AI 활용 고지: 이 문서는 생성형 AI로 초안을 구성하고, 원영상 맥락과 공식 문서를 바탕으로 검토해 정리했습니다.

그래프 뷰

백링크