AI 학습 문서 개선 기준
목표
이 폴더의 목표는 AI 연구자가 되는 것이 아니라, 백엔드 개발자가 AI 기능을 실제 서비스에 붙이고 운영할 수 있는 판단력을 갖추는 것이다.
좋은 AI 백엔드 개발자는 모델 이름을 많이 아는 사람이 아니라, 다음 질문에 답할 수 있는 사람이다.
- 이 기능은 동기 API로 처리할 수 있는가, 비동기 작업으로 빼야 하는가?
- 실패하면 사용자는 무엇을 보게 되는가?
- timeout, retry, rate limit, circuit breaker는 어디에 둘 것인가?
- 모델 응답을 DTO로 안전하게 받을 수 있는가?
- RAG 검색 결과에 사용자 권한이 반영되는가?
- 비용이 폭증하면 어떤 제한이 먼저 동작하는가?
- 인프라팀은 어떤 지표와 용량 계획을 원할까?
- 보안팀은 어떤 데이터 흐름과 감사 로그를 요구할까?
AOP 문서에서 가져올 스타일
Spring AOP 문서는 개념을 단순 정의로 끝내지 않고, 공식 문서의 핵심 문장, 동작 원리, 설계 판단 기준, 실전 팁, 위험 신호, 확인 질문으로 이어진다.
AI 문서도 같은 방식으로 작성한다.
- 압축 정리 문서는 여러 하위 주제를
#제목으로 묶고, 각 제목마다### 3줄 요약,### 핵심 정리,### 헷갈리는 지점,### 확인 질문을 둔다. - 상세 문서는 최상단 H1을 쓰지 않는다. 파일명이 제목 역할을 한다.
- 상세 문서의 첫 블록은 Obsidian callout으로 시작한다.
- 본문 heading은
##단일 계층으로 평평하게 둔다. - 확인 질문은 질문 bullet 아래에 답변 bullet을 들여쓴다.
- 참고 문서는 공식 문서, 공식급 문서, 권위 있는 자료를 우선한다.
AI 문서에서 추가로 강화할 축
AI 기능은 실무에서 기술 단위로 문제가 오지 않는다. 대부분 다음처럼 증상으로 온다.
- 답변이 느리다.
- 비용이 갑자기 늘었다.
- JSON 응답이 깨진다.
- RAG가 엉뚱한 문서를 찾는다.
- tool calling이 같은 작업을 두 번 실행했다.
- 보안팀이 prompt injection과 개인정보 유출을 걱정한다.
- 인프라팀이 GPU, 벡터 DB, 외부 API 의존성, 로그 비용을 걱정한다.
따라서 각 문서는 개념 설명에 그치지 않고 다음 관점을 적극적으로 포함한다.
- 백엔드 설계 판단
- 코드로 이해하기
- 장애 상황과 대응
- 인프라 협업 포인트
- 개인 프로젝트 최소 기준
- 기업 운영 수준 기준
- 주니어 관점
- 시니어 관점
- 실전 팁
- 위험 신호!
현재 실무 기술과 낮은 우선순위 기술 구분
AI 생태계는 변화가 빠르기 때문에 모든 기술을 같은 깊이로 공부하지 않는다.
- 현재 실무에서 꼭 알아야 하는 것은 깊게 다룬다.
- 특정 환경에서만 유용한 것은 조건을 명확히 적는다.
- 개인 프로젝트에는 과하지만 기업 운영에서는 필요한 것은 성숙도 기준으로 분리한다.
- 예전에는 유행했지만 지금은 우선순위가 낮은 것은 짧게만 언급한다.
- 유지보수가 약하거나 사양된 방식은 깊게 파지 않는다.
예를 들어 단일 프롬프트 튜닝만으로 품질을 해결하려는 접근은 이제 한계가 뚜렷하다. 현재 실전에서는 prompt engineering, context engineering, harness engineering을 함께 봐야 한다. 반대로 거대한 autonomous agent를 아무 안전장치 없이 붙이는 방식은 데모에는 좋아도 운영 서비스에서는 위험 신호에 가깝다.
기존 AI 문서 흡수 원칙
기존 Blog/posts/AI에는 Python 문법, 자료형, 함수, 리스트 컴프리헨션, itertools, 프롬프트 요청 양식 메모가 있다.
이 내용은 다음 위치로 흡수한다.
- Python 함수, 기본 인자,
*args,**kwargs, lambda, closure는 AI 개발 환경과 하네스 코드 예시에 흡수한다. - 자료형, dict, Counter, list 변환은 JSON schema, context 조립, eval 집계 예시에 흡수한다.
- 리스트 컴프리헨션과 itertools는 eval dataset 생성, RAG chunk 처리, 조합 테스트 예시에 흡수한다.
- Python 관례와 keyword argument 메모는 AI 코드의 가독성, 명시적 인자, 운영 코드 리뷰 기준에 흡수한다.
- 프롬프트 글쓰기 메모의 “왜 그런 구조가 필요한지 중심으로 설명” 관점은 모든 상세 문서의 기본 문체에 반영한다.
코드 예시 기준
코드는 장식이 아니라 학습 도구여야 한다.
- 단순 호출만 보여주지 않는다.
- 실패 케이스, 예외 처리, 검증, timeout, retry, logging 중 최소 하나 이상을 포함한다.
- 백엔드 계층 구조를 드러낸다.
- 필요한 경우 Java Spring Boot API 서버, Python worker, TypeScript tool server를 함께 사용한다.
- 코드가 길어지면 핵심 흐름만 남기되 실제 구현 감각을 잃지 않게 한다.
개인 프로젝트 최소 기준
개인 프로젝트라도 수준 있는 결과물을 내려면 다음은 최소로 챙긴다.
- 모델 호출 timeout
- 간단한 retry/backoff
- structured output 검증
- 사용자 입력과 모델 응답 로그의 민감정보 마스킹
- 사용자별 비용 제한 또는 일일 호출 제한
- 프롬프트 버전 기록
- 작은 eval 샘플셋
- RAG를 쓴다면 문서 삭제와 재색인 절차
기업 운영 수준 기준
기업 운영 수준에서는 다음이 추가된다.
- SLO와 장애 대응 런북
- provider 장애 시 fallback 또는 degrade mode
- 테넌트별 quota와 비용 예산
- 개인정보 처리 경계와 데이터 보존 정책
- 권한 기반 RAG 필터링
- audit log와 trace
- prompt/model/index 변경 관리
- eval regression gate
- 인프라 용량 계획과 observability 비용 관리
- 보안팀과 prompt injection, tool 권한, MCP server 노출 범위 합의