sentenz/technical-article

기술 문서

AI 에이전트가 공식적인 언어, 일관된 구조, 정확한 용어, 실용적인 예제 및 검증 가능한 참조를 사용하여 기술 문서를 생성, 수정 및 검토하기 위한 지침입니다.

• 1. 이점
• 2. 원칙
  • 2.1. 언어
  • 2.2. 콘텐츠 무결성
• 3. 구조
  • 3.1. 파일 및 제목
  • 3.2. 소개
  • 3.3. 목차
  • 3.4. 번호가 매겨진 섹션
  • 3.5. 분류 체계와 정의
  • 3.6. 예제와 데이터
  • 3.7. 참조
• 4. 워크플로우
  • 4.1. 생성
  • 4.2. 수정
  • 4.3. 검토
• 5. 스타일 가이드
  • 5.1. 어조와 말투
  • 5.2. 용어
  • 5.3. 문장과 단락
  • 5.4. 목록과 인용문
  • 5.5. 링크와 인용
  • 5.6. 코드, 표, 주의사항
• 6. 품질 관문
• 7. 리소스
• 8. 참조

1. 이점

• 일관성

  안정적인 문서 문법은 주제 전반에 걸쳐 기술 콘텐츠를 예측 가능하게 만들고, 독자가 문서 구조를 다시 배울 필요 없이 정의, 분류, 원칙, 예제 및 참조를 찾을 수 있게 합니다.

• 가독성

  간결한 정의 단락, 명시적 제목, 용어-정의 목록은 인지 부하를 줄이면서 기술적 정밀도를 유지합니다.

• 탐색 용이성

  수동으로 유지 관리되는 계층적 목차와 번호가 매겨진 제목은 개념적 계층 구조를 드러내고 긴 문서에서 직접 탐색을 제공합니다.

• 재사용성

  분류 체계, 용어 목록, 실용적인 예제 및 검증된 참조는 각 문서를 소개이자 내구성 있는 엔지니어링 참고 자료로 유용하게 만듭니다.

• 검토 용이성

  결정론적 형식 및 증거 규칙을 통해 검토자는 구조적 결함, 언어 결함 및 기술적 부정확성을 분리할 수 있습니다.

2. 원칙

2.1. 언어

• 공식적

  소프트웨어 엔지니어, 시스템 엔지니어, 보안 전문가 및 기술 의사 결정권자에게 적합한 중립적인 한국어를 사용합니다.

• 백과사전적

  관행을 규정하기 전에 주제를 정의합니다. 권장 사항을 제시하기 전에 개념이 무엇인지, 어떻게 분류되는지, 어디에 적용되는지 설명합니다.

• 정확함

  광범위하거나 홍보적인 표현보다 도메인별 명사와 동사를 선호합니다. 표준, 사양, 프로토콜, 도구, 프레임워크, 관행, 메트릭 및 아키텍처 패턴을 구분합니다.

• 비개인적

  3인칭 또는 비인칭 구문을 선호합니다. 1인칭 서술, 직접적인 2인칭 호칭, 수사적 질문 및 대화식 잡담을 피합니다.

• 선언적

  정의, 관계, 제약 조건 및 결과를 직접적으로 명시합니다. 실제 요구 사항, 권장 사항, 가능성 또는 불확실성을 표현할 때만 조동사를 사용합니다.

2.2. 콘텐츠 무결성

• 증거

  외부에서 검증 가능한 주장은 권위 있는 출처로 뒷받침합니다. 표준 기관, 공식 문서, 1차 연구 및 표준 저장소를 선호합니다.

• 최신성

  시간에 민감한 사실, 버전별 동작, 성능 임계값, 법적 요구 사항 및 제품 기능을 포함하기 전에 확인합니다.

• 범위

  각 문서를 하나의 기술 주제에 집중시킵니다. 상당한 배경 자료를 복제하기보다는 인접 문서에 링크합니다.

• 분류의 일관성

  한 번에 하나의 명시적 분류 차원으로 개념을 그룹화합니다. 섹션이 관계를 설명하지 않는 한 도구, 관행, 결과 및 속성을 동등한 수준으로 혼합하지 마십시오.

• 예제

  구문적으로 유효하고, 기술적으로 타당하며, 앞의 설명과 직접적으로 연결된 예제를 사용합니다.

3. 구조

3.1. 파일 및 제목

• 파일 이름

  주제를 식별하는 소문자 케밥 케이스(kebab-case) 파일 이름을 사용합니다. 예: technical-debt.md, feature-flags.md, file-systems.md

• 머리말

  대상 저장소에서 명시적으로 요구하지 않는 한 문서 파일에 YAML 머리말을 추가하지 마십시오.

• H1 제목

  정확히 하나의 H1 제목으로 시작하며, 표준 주제 이름을 제목 케이스로 포함합니다.

  # Feature Flags
  

3.2. 소개

H1 제목 바로 뒤에 한두 개의 간결한 단락을 배치합니다.

1. 정의

   첫 번째 문장에서 주제를 정의합니다. 문서 도메인에서 보편적으로 자명하지 않은 경우 첫 사용 시 약어를 풉니다.

2. 맥락

   주제의 목적, 운영 역할 또는 소프트웨어 엔지니어링과의 관계를 설명합니다. 목차 이전에는 상세한 분류를 도입하지 않습니다.

예시:

# Feature Flags

Feature flags는 새 배포 없이 애플리케이션 동작을 활성화 또는 비활성화하는 런타임 제어 장치입니다. 코드 배포와 기능 출시를 분리하여 통제된 롤아웃, 실험 및 운영 완화를 지원합니다.

3.3. 목차

소개 이후, 첫 번째 H2 섹션 이전에 수동으로 유지 관리되는 Markdown 목차를 삽입합니다.

• 계층 구조

  번호가 매겨진 모든 H2, H3 및 주요 H4 제목을 수준당 두 칸 들여쓰기로 미러링합니다.

• 레이블

  전체 숫자 접두사와 제목 텍스트를 포함합니다.

• 앵커

  GitHub 호환 소문자 앵커를 사용합니다. GitHub 제목 규칙에 따라 구두점을 제거하면서 단어 사이의 하이픈은 유지합니다.

• 완전성

  제목이 변경될 때마다 목차 항목을 추가, 제거 또는 이름을 변경합니다.

예시:

- [1. 분류](#1-분류)
  - [1.1. 배포 전략](#11-배포-전략)
    - [1.1.1. 블루-그린 배포](#111-블루-그린-배포)
    - [1.1.2. 카나리아 배포](#112-카나리아-배포)
- [2. 원칙](#2-원칙)
- [3. 모범 사례](#3-모범-사례)
- [4. 용어](#4-용어)
- [5. 참조](#5-참조)

3.4. 번호가 매겨진 섹션

H1 아래의 모든 문서 제목에 아라비아 숫자 10진법 번호 매기기를 사용합니다.

• H2

  최상위 섹션에는 ## 1. <섹션>을 사용합니다.

• H3

  2차 레벨 섹션에는 ### 1.1. <하위 섹션>을 사용합니다.

• H4

  하위 섹션에 다른 수준이 필요한 상당한 분류가 포함된 경우에만 #### 1.1.1. <주제>를 사용합니다.

• 깊이

  H1을 포함하여 4개 이상의 제목 수준을 선호하지 않습니다. 과도한 제목 깊이는 용어-정의 목록 또는 표로 대체합니다.

• 표준 섹션

  주제에 기여하는 섹션만 선택합니다. 일반적인 말뭉치 호환 레이블에는 이점, 분류, 원칙, 원칙들, 모범 사례, 용어 및 참조가 포함됩니다.

• 순서

  기본 개념과 분류로 시작하여 원칙 또는 관행으로 계속 진행한 다음 용어와 참조로 결론을 내립니다.

3.5. 분류 체계와 정의

개념적 전환에는 산문을, 스캔 가능한 기술 콘텐츠에는 용어-정의 목록을 사용합니다.

• 섹션 리드

  주요 섹션을 분류 차원 또는 섹션의 목적을 설명하는 하나 또는 두 개의 단락으로 시작합니다.

• 용어-정의 패턴

  기술 레이블을 글머리 기호로, 설명을 들여쓰기된 인용문으로 제시합니다.

  - 원자성(Atomicity)
    > 원자성은 트랜잭션이 하나의 단위로 완료되거나 부분 결과를 유지하지 않고 롤백되도록 보장합니다.
  

• 그룹화 패턴

  하위 섹션에 규칙, 예제 또는 도구와 같은 여러 개의 개별적인 관점이 포함된 경우 순서 목록 항목을 로컬 그룹 제목으로 사용합니다.

• 레이블 대문자화

  개념적 레이블에는 제목 케이스(title case)를, 설명에는 문장 케이스(sentence case)를 사용합니다.

• 설명 품질

  용어의 역할, 동작 또는 정의 속성으로 설명을 시작합니다. 의미를 추가하지 않고 레이블을 반복하는 순환 정의를 피합니다.

3.6. 예제와 데이터

• 독립형 예제

  산문 수준의 독립형 예제는 예시:로 소개합니다. 예제 및 설명과 같은 그룹화된 하위 섹션 내에서는 대신 설명적인 예제 레이블을 사용합니다.

• 코드 예제

  가장 정확한 언어 식별자를 사용하여 펜스 코드 블록을 사용합니다.

• 인라인 구문

  명령, 파일 경로, 구성 키, 식별자, 리터럴 및 짧은 구문 조각에는 백틱을 사용합니다.

• 표

  간결한 비교, 행렬, 메트릭, 명령 또는 열거된 참조 데이터에는 Markdown 표를 사용합니다. 셀 내용을 병렬로 유지하고 셀 내부에 산문 단락을 피합니다.

• 다이어그램

  산문이나 표로 관계나 흐름을 효율적으로 설명할 수 없는 경우 Mermaid와 같은 텍스트 기반 다이어그램을 사용합니다.

• 주의 사항

  GitHub 주의 사항(constraint), 경고(caveat), 상호 링크 또는 해석을 실질적으로 변경하는 정보에 대해서는 GitHub 주의 사항을 드물게 사용합니다.

  > [!NOTE]
  > 메트릭 임계값은 인용된 보고 기간에 따라 다르며 게시 전에 확인해야 합니다.
  

3.7. 참조

모든 문서를 번호가 매겨진 참조 섹션으로 끝냅니다.

• 내부 참조

  관련 Sentenz 문서에는 저장소 상대 링크를 사용합니다.

  - Sentenz [버전 관리](../articles/versioning.md) 문서.
  

• 외부 참조

  연결된 제목 앞에 조직 또는 게시자를 명시하고 링크 뒤에 출처 유형을 식별합니다.

  - NIST [Secure Software Development Framework (SSDF) Version 1.1](https://csrc.nist.gov/pubs/sp/800/218/final) 간행물.
  - Kubernetes [Documentation](https://kubernetes.io/docs/) 문서.
  - GitHub [DORA Four Keys](https://github.com/dora-team/fourkeys) 저장소.
  

• 출처 유형

  문서, 문서화, 페이지, 간행물, 저장소, 보고서, 명세 또는 표준과 같은 정확한 한정자를 사용합니다.

• 관련성

  문서에서 인용되었거나 실질적으로 사용된 출처만 포함합니다. 문서 주장과 관련 없는 일반적인 독서 목록을 작성하지 마십시오.

4. 워크플로우

4.1. 생성

1. 점검

   대상 문서 디렉토리의 주변 파일을 읽습니다. 로컬 제목 어휘, 링크 스타일, 코드 펜스 규칙 및 관련 내부 문서를 기록합니다.

2. 범위 설정

   문서 주제, 의도된 깊이 및 기본 분류 차원을 정의합니다. 인접한 주제를 상호 연결된 문서로 분리합니다.

3. 조사

   권위 있는 1차 출처를 수집합니다. 용어, 표준, 메트릭, 제품 동작 및 시간에 민감한 세부 사항을 확인합니다.

4. 개요 작성

   필요한 표준 섹션을 선택하고 산문을 작성하기 전에 번호가 매겨진 제목 계층 구조를 구성합니다.

5. 템플릿 로드

   새 문서를 만들 때 assets/technical-article-template.md를 로드합니다. 주제에 기여하지 않는 섹션을 제거합니다.

6. 소개 초안 작성

   H1 제목과 한두 개의 정의 단락을 작성합니다. 구현 세부 사항을 먼저 제시하지 않고 주제와 엔지니어링 맥락을 설정합니다.

7. 목차 구축

   계획된 제목 계층 구조를 미러링하고 정확한 GitHub 호환 앵커를 생성합니다.

8. 섹션 작성

   섹션 리드, 용어-정의 목록, 예제, 표, 다이어그램 및 주의 사항을 이해를 향상시키는 경우에만 추가합니다.

9. 참조 추가

   내부 상대 링크 및 외부 출처 확인된 참조를 추가합니다. 모든 중요한 외부 주장에 적절한 권위 있는 출처가 있는지 확인합니다.

10. 검증

    문서를 반환하거나 커밋하기 전에 모든 품질 관문을 적용합니다.

4.2. 수정

1. 의도 유지

   구조를 변경하기 전에 기존 문서의 주제, 범위 및 분류 체계를 식별합니다.

2. 템플릿 로드

   문서를 수정하기 전에 assets/technical-article-template.md를 로드합니다. 구조적 기준선으로 사용하고, 적용할 수 없는 템플릿 섹션을 제거하며, 유효한 문서별 섹션을 유지합니다.

3. 진단

   결함을 기술적 정확성, 분류, 구성, 언어, 서식, 링크, 예제 및 참조로 분리합니다.

4. 정규화

   제목, 소개, 목차, 번호 매기기, 제목 수준, 목록, 인용문, 코드 펜스 및 참조를 이 스킬에 맞춥니다.

5. 언어 개선

   모호하거나, 반복적이거나, 대화체이거나, 홍보적인 표현을 직접적인 기술적 정의와 도메인에 적절한 동사로 대체합니다.

6. 탐색 조정

   제목이나 파일 이름이 변경될 때마다 앵커, 상호 링크 및 참조를 업데이트합니다.

7. 검증

   모든 품질 관문을 다시 실행하고 명시적인 이유 없이 기술적으로 관련된 정보가 제거되지 않았는지 확인합니다.

4.3. 검토

1. 템플릿 로드

   문서를 검토하기 전에 assets/technical-article-template.md를 로드합니다. 구조적 기준선으로 사용하고, 생략된 선택적 섹션이 완전성 또는 일관성 문제를 일으키지 않는 한 결함으로 보고하지 마십시오.

2. 평가

   다음 순서로 문서를 검토합니다.

   1. 기술적 정확성
   2. 범위 및 분류 일관성
   3. 구조적 준수
   4. 용어 및 약어
   5. 예제, 표 및 다이어그램
   6. 링크 및 참조
   7. 문법, 구두점 및 가독성

3. 결과 보고

   영향받는 제목 또는 줄, 결함, 기술적 결과 및 구체적인 수정 사항과 함께 결과를 보고합니다. 스타일 선호도보다 사실 오류 및 구조적 불일치에 우선 순위를 둡니다.

5. 스타일 가이드

5.1. 어조와 말투

• 현재 시제

  정의, 기능 및 현재 관행에는 현재 시제를 사용합니다.

• 과거 시제

  역사적 사건이나 대체된 동작에 대해서만 과거 시제를 사용합니다.

• 능동태

  행위자나 메커니즘이 중요한 경우 능동태를 선호합니다.

• 수동태

  프로세스나 결과가 초점이고 행위자가 중요하지 않은 경우 수동태를 사용합니다.

• 비인칭 관점

  1인칭 및 2인칭 대명사를 피합니다.

  …

  [번역을 위해 잘림]