Skip to content

CONTENT-GUIDE.md

Latest commit

 

History

History
237 lines (162 loc) · 15.8 KB

CONTENT-GUIDE.md

File metadata and controls

237 lines (162 loc) · 15.8 KB
Raw

콘텐츠 운영 가이드

콘텐츠 타입별 역할

타입 성격 비유 시간성
Blog 의견·분석·논평 칼럼, 에세이 시점이 중요 (그때 그 생각)
Guide 종합 레퍼런스 교과서, 핸드북 에버그린 (계속 업데이트)
Study 학습 기록 수강 노트, 독서 노트 학습 과정 기록
Project 만든 것 포트폴리오 완성 시점

판단 기준

"X에 대한 내 생각/분석이 있다" → Blog
"X를 처음부터 끝까지 정리한 레퍼런스다" → Guide
"X를 공부하고 있다" → Study
"X를 만들었다" → Project

Blog ↔ Guide 관계 원칙

Blog = Why & What (왜 중요한가, 무슨 일이 벌어지고 있는가) Guide = How (어떻게 하는가, 상세 레퍼런스)

  • 블로그에서 가이드 내용을 반복하지 않는다
  • 블로그는 "읽을 이유"를 주고, 가이드로 보낸다
  • 가이드는 블로그 없이도 독립적으로 읽을 수 있어야 한다

좋은 예

[Blog] "AI Native 팀이 왜 필요한가" — 현상 분석, 인사이트 2~3개, 가이드 링크
[Guide] "AI Native 팀 운영 가이드" — 6원칙, 4역할, 5안티패턴, 5단계 로드맵 (본체)

나쁜 예

[Blog] 6원칙, 4역할, 5안티패턴, 5단계 로드맵 전부 포함 (3000자+)
[Guide] 블로그와 동일 내용 반복

Blog ↔ Blog 중복 방지

각 포스트는 하나의 고유한 테제(주장)를 가져야 한다

글 쓰기 전에 한 문장으로 테제를 정리한다:

  • "AI가 콘텐츠 생태계 3축을 동시에 바꾸고 있다" (현상 분석)
  • "AI에게 인용되려면 GEO 전략이 필요하다" (대응 전략)

테제가 한 문장으로 안 되면 범위를 좁힌다.

겹치는 데이터 처리

  • 한쪽에서 상세히 다루고, 다른 쪽에서는 인용 + 링크
  • 같은 현상의 다른 면을 다루는 경우, 서두에 관계를 명시한다:

    "이전 글에서 X를 다뤘고, 이번엔 Y에 집중한다"

Guide ↔ Guide 관계

가이드 간 관계는 명시적으로 연결한다:

agent (개론) → "패턴 심화는 agentic-patterns 가이드 참고"
agentic-patterns (심화) → "기초 개념은 agent 가이드 참고"

관련 가이드끼리 서로 링크를 걸어 독자가 자연스럽게 이동할 수 있게 한다.

새 글 쓸 때 체크리스트

  1. 이미 비슷한 내용이 있는가? — 기존 블로그/가이드 목록 확인
  2. 이건 Blog인가 Guide인가? — 의견/분석이면 Blog, 레퍼런스면 Guide
  3. 기존 글과 겹치는 데이터가 있는가? — 있으면 링크로 연결, 반복하지 않기
  4. 이 글의 고유한 테제는? — 한 문장으로 정리

기술 분석의 깊이와 근거

기술 분석의 목표는 독자가 이 변화로 자신의 작업과 시스템을 어떻게 바꿀 수 있는지 판단하게 하는 것이다. 기능 목록, 가격표, 벤치마크, 공식 문서 요약은 분석의 재료다. 이것만으로 기술 분석을 완료하지 않는다. 사용자가 별도로 요구하지 않아도 활용 방식과 설계상의 함의까지 조사한다.

조사와 논증

  • 먼저 기존 방식의 구체적인 문제와 이번 분석에서 답할 질문을 정한다. 발표 자료 순서대로 글을 구성하지 않는다.
  • 공식 문서로 기능과 조건을 확인하고, 공개 구현·코드·실험·실사용 사례에서 실제 적용 방식을 조사한다. 문서만 읽었다면 그 범위를 밝힌다.
  • 핵심 주장마다 기존 문제 → 기술적 변화 → 가능한 설계 변경 → 기대 효과 → 성립 조건과 검증 방법을 연결한다. 연결을 입증할 자료가 없으면 설계 제안 또는 가설로 명시한다.
  • 원래 있던 기법과 새 기술의 기여를 구분한다. 기존 아키텍처를 모델이 제안한 사례를 새로운 아키텍처의 발명이나 해당 모델만의 능력으로 확대하지 않는다.
  • 제품명·약어·프로젝트의 역할은 출처에서 확인한다. 모르는 이름을 추측으로 풀어 쓰지 않는다.

기존 사용자에게 필요한 비교와 전환 안내

모델·도구의 출시 및 업그레이드 분석은 기존 사용자의 다음 세 질문에 반드시 답한다.

  1. 내가 쓰던 것보다 무엇이 나아졌는가? 비교할 모델·버전·설정을 명시하고, 기존에 자주 실패하거나 사람이 개입하던 작업이 어떻게 달라지는지 설명한다. 같은 회사의 직전 버전뿐 아니라 글의 독자가 사용하던 다른 모델도 관련성이 있으면 비교한다. 근거가 없는 우열은 단정하지 않는다.
  2. 그 개선을 어떻게 활용하는가? 맡길 작업, 제공할 맥락과 완료 기준, 실행 환경, 필요한 도구·설정을 구체적으로 제시한다. 모델 자체의 개선과 특정 API·앱·런타임을 연결해야 얻는 효과를 구분한다. 모델 이름만 바꿔도 새 실행 기능이 활성화된다고 가정하지 않는다.
  3. 기존 구성에서 무엇을 고쳐야 하는가? 기존 프롬프트·스킬·하네스·Agent Loop·도구 인터페이스·권한 및 승인·검증 절차 중 관련 항목을 골라 수정 전후와 이유를 보여준다. 기존 모델의 약점을 보완하던 우회책이 여전히 필요한지도 검토한다. 필수 호환성 수정, 선택적 최적화, 유지할 구성을 구분하고 변경의 우선순위를 제시한다.

핵심 변화는 가능한 경우 기존 작업과 문제 / 개선 근거 / 활용 방법 / 수정할 구성 / 확인할 결과로 연결한다. 모든 항목을 형식적인 표로 채우기보다 독자가 자신의 구성에 적용할 수 있을 만큼 구체적으로 쓴다. 새 모델의 능력 향상을 이유로 필요한 통제를 일괄 제거하도록 권하지 않는다.

전환 안내에는 같은 대표 과제에서 기존 구성을 기준선으로 측정하고, 모델 교체와 구성 수정을 나눠 비교하는 방법을 포함한다. 성공률·사람의 개입·총비용·시간 등 해당 작업의 채택 기준을 정하고, 개선이 없을 때 기존 구성을 유지하거나 되돌릴 조건도 설명한다. 실제 전환을 시험하지 않았다면 검증된 절차와 제안한 실험을 구분한다.

실제 활용을 설명하는 수준

핵심 테제를 뒷받침하는 구체적인 활용 시나리오를 최소 하나 다룬다. 누가 어떤 입력과 환경에서 무엇을 맡기는지, 기존 절차와 결과가 어떻게 달라지는지 설명한다. 직접 관찰한 사례인지, 타인의 경험담인지, 글에서 만든 예시인지 구분한다.

설계에 영향을 주는 기술이라면 구성요소의 책임과 실행 흐름까지 설명한다. 모델·호스트 프로그램·도구·사람 중 누가 판단하고 실행하고 검증하는지 보여준다. 필요한 경우 짧은 코드, 전후 비교표, 흐름도를 사용한다. 블로그에는 주장을 이해하는 데 필요한 구현 설명을 담고, 전체 튜토리얼은 가이드로 연결한다.

예를 들어 에이전트 하네스 분석에서는 다음 질문이 유용하다. 모든 기술 문서에 이 사례를 억지로 적용하지는 않는다.

  • 반복해서 프롬프트로 전달하던 규칙 중 어떤 것을 호스트 코드로 집행할 수 있는가? 여전히 모델의 의미 판단이 필요한 부분은 무엇인가?
  • 작업을 진행하는 Agent Loop와 금지 행동을 차단하는 장치의 책임은 어떻게 나뉘는가?
  • 장치가 늘어도 모델이 읽는 문맥과 반복 판단이 줄어드는 이유는 무엇인가? 도구 출력 등으로 부담이 다시 늘어나는 경로는 없는가?
  • OS나 Bash, 네이티브 바이너리로 옮긴 통제가 모든 관련 실행 경로에 적용되는가? 우회 가능성과 실패 시 동작은 무엇인가? 구현 언어나 실행 위치만으로 강제력을 단정하지 않는다.

근거와 효과의 구분

  • 공식적으로 확인한 사실, 공급자의 평가, 사용자의 경험담, 필자의 해석·제안, 직접 측정 결과를 문맥에서 명확히 구분한다. 경험담을 재현된 사실이나 자신의 실험처럼 쓰지 않는다.
  • 토큰·턴·비용·시간·품질을 별개로 다룬다. 턴 감소만으로 비용 절감이나 성능 향상을 확정하지 않는다. 가능한 경우 같은 과제와 완료 기준에서 재시도, 사람의 개입, 결과 품질을 함께 비교한다.
  • 측정값이 없어도 작동 원리와 검증할 가설을 분석할 수 있다. 수치를 만들거나 효과를 보장하지 말고 무엇을 비교해야 하는지 적는다.
  • AGI 같은 큰 해석은 관찰된 능력과 연결하고, 그 사례가 입증하지 못하는 범위를 설명한다. 과장을 피한다는 이유로 설계 판단·일반화·자율 수행의 의미 자체를 생략하지 않는다.
  • 사용자에게 받은 사례는 분석의 출발점이다. 공개 인용할 때는 원문·작성자·맥락과 공개 여부를 확인하고, 확인 전에는 출처가 확보된 공개 사례처럼 발행하지 않는다.

실전 사용 가이드의 조사 범위

출시 모델의 실전 사용을 다루면 성능 비교, 제품별 접근 조건, 과금 단위와 사용량, 버전·설정, 장시간 작업의 상태 유지, 기존 지침 수정, 실제 작업 예시와 중단 대처를 먼저 조사한다. 독자에게 관련된 항목을 하나의 사용 순서로 구성하고, 지적받은 기능만 따로 덧붙여 완성도를 판단하지 않는다. 일반적인 콘텐츠 분류 원칙보다 사용자가 명시한 글의 범위와 형식을 우선한다.

추론 수준의 효율 팁은 원 평가·버전·지표·비용 단위·비교 조건을 확인한다. 벤치마크의 점수 차이를 포괄적인 지능 백분율로 바꾸거나, API 비용을 구독 사용량 절감률로 바꾸지 않는다. 출처가 불분명한 정확한 숫자는 권장값으로 제시하지 않고, 같은 과제에서 검증할 절차를 설명한다.

완료 전 검토

  1. 가격표와 기능 목록을 빼도 이 글만의 설명과 판단이 남는가?
  2. 독자가 실제로 바꿔볼 작업이나 설계 선택을 구체적으로 알 수 있는가?
  3. 그 선택이 효과를 내는 원리와 적용 조건을 설명했는가?
  4. 사실·경험담·추론·측정을 구분하고 핵심 주장에 근거를 연결했는가?
  5. 실패할 조건과 효과를 확인할 방법이 해당 사례에 맞게 구체적인가?
  6. 대화에서 설명한 분석이 실제 원고에도 반영됐는가? 완료 보고 전에 본문을 확인한다.
  7. 출시·업그레이드 분석이라면 기존 사용자가 개선점, 활용법, 수정할 구성과 우선순위를 알 수 있는가?

자료가 부족해 활용 분석에 이르지 못했다면 조사·보강하거나 문서의 범위를 명시한다. 발표 요약을 심층 분석으로 보고하지 않는다.

한국어 문체 가이드

한국어 글은 영어 글의 문장 구조를 옮기지 않고 처음부터 한국어 설명문으로 쓴다. 사실과 코드 흐름을 먼저 보여주고, 판단은 독자가 자연스럽게 따라올 수 있도록 뒤에 둔다.

제목

  • 무엇을 다루는 글인지 바로 알 수 있게 쓴다
  • A가 아니라 B다, 진짜 제품은, X의 본질, 왜 모두가 틀렸나 같은 영미권 테크 블로그 공식을 기본값으로 쓰지 않는다
  • 대시(—)로 두 개의 주장을 억지로 연결하지 않는다
  • 강한 주장이 실제 내용보다 앞서지 않게 한다
나쁨: Docker 래퍼가 아니라 에이전트의 실행 프로토콜이다 — OpenSandbox 해부
좋음: OpenSandbox 코드 분석: AI 에이전트의 실행 환경을 어떻게 통일했나

도입부

  • 수사적 질문이나 반전 문장으로 억지로 시작하지 않는다
  • 독자가 알아야 할 배경, 살펴본 대상, 글에서 다룰 범위를 3~4문단 안에 설명한다
  • 처음엔 X인 줄 알았다. 하지만 진짜는 Y였다 같은 인위적인 발견 서사를 반복하지 않는다
  • 스타 수나 벤치마크는 관심을 끄는 장식이 아니라 분석 대상을 설명하는 근거로만 쓴다

문장

  • 명사보다 동사를 쓴다: 실행의 추상화를 제공한다보다 실행 환경의 차이를 숨긴다
  • 제품, 가치, 경계, 표면, 레이어, 포지션, 작동한다 같은 번역투 단어를 반복하지 않는다
  • 영어 용어가 더 정확할 때만 원어를 쓰고, 자연스러운 한국어가 있으면 바꾼다
  • 한 문장에 주장과 비유와 결론을 모두 넣지 않는다
  • 같은 문형을 연달아 쓰지 않는다. 특히 X가 아니다. Y다., 첫째/둘째/셋째, 이 지점이다, 셈이다의 반복을 피한다
  • 굵은 글씨는 핵심 용어나 꼭 기억할 결론에만 사용한다. 문단마다 한 문장씩 강조하지 않는다
나쁨: 격리 기술을 제품 정체성에서 교체 가능한 백엔드로 내린다.
좋음: gVisor, Kata, Firecracker를 바꿔도 같은 API를 사용할 수 있다.

나쁨: 이 프로젝트의 진짜 가치는 짧은 수명의 컴퓨트를 배급하고 회수하는 제어 시스템이라는 점이다.
좋음: Pool은 미리 준비한 샌드박스를 할당하고, 사용이 끝나면 회수한다.

구성과 결론

  • 소제목은 광고 문구보다 내용을 설명하는 말로 쓴다: 남는 것보다 정리, 누가 써야 하나보다 어떤 경우에 적합한가
  • 장점과 한계를 별도 근거와 함께 쓴다. 균형을 맞추기 위한 형식적인 반론은 넣지 않는다
  • 글의 주장을 문단마다 반복하지 않는다
  • 결론에서는 본문을 다시 요약한 뒤, 확인된 사실의 범위 안에서 판단한다
  • 독자에게 질문을 던지거나 한 줄짜리 선언으로 억지 여운을 만들지 않는다

한·영 쌍 작성

  • 두 글의 사실, 날짜, 수치, 링크, 결론은 맞춘다
  • 문장 구조와 제목 공식까지 같게 만들 필요는 없다
  • 영어 원고를 먼저 썼더라도 한국어판은 번역하지 말고 같은 자료로 다시 쓴다

발행 전 한국어 퇴고

  1. 제목이 A가 아니라 B 또는 대시 두 문장 구조인가? 더 직접적인 제목으로 바꾼다
  2. 첫 세 문단에 과장된 질문, 반전, 선언이 몰려 있는가? 배경과 범위부터 설명한다
  3. 제품·가치·경계·표면·레이어·핵심·본질·진짜가 반복되는가? 구체적인 구성요소와 동작으로 바꾼다
  4. X가 아니다. Y다. 문형이 두 번 이상 나오는가? 사실을 바로 서술한다
  5. 굵은 문장이 문단마다 있는가? 꼭 필요한 강조만 남긴다
  6. 소제목만 읽어도 각 절의 내용을 예상할 수 있는가?
  7. 마지막 문단이 새로운 거대 주장이나 수사적 질문으로 끝나는가? 본문에서 확인한 범위로 줄인다
  8. 소리 내어 읽었을 때 실제로 한국어로 설명하는 말처럼 들리는가?

콘텐츠 정리 이력

2026-05-04 완료

  • Blog 06 ai-native → 155줄 → 65줄로 축약. 6원칙/4역할/5안티패턴/5단계 로드맵 삭제, 핵심 인사이트 3개 + 가이드 링크로 정리
  • Blog 08 interview-guide → 이미 가이드 소개 형태로 적절. 유지
  • Blog 04 ↔ 05 → 상호 링크 추가 (04 끝에 05 링크, 05 서두에 04 참조)
  • Blog 09 ai-dlc → 역할 재배치 섹션에 AI Native 가이드 링크 추가
  • Guide roadmap (draft) → 삭제 (빈 stub, developer-roadmap과 중복)
  • Guide agent ↔ agentic-patterns → 상호 링크 추가

한/영 다국어 운영

  • 모든 콘텐츠는 ko/en 쌍으로 관리
  • 같은 폴더 slug, 같은 날짜, 같은 태그 유지
  • 한쪽을 수정하면 다른 쪽도 동기화