새 글 기여하기

0. 이 글을 읽는 대상

• 사람 기여자
• AI 에이전트 (이 가이드만 보고도 글 한 편 + 배포까지 끝낼 수 있어야 한다)

1. 글 한 편의 형식

모든 글은 다음 5섹션 구조를 따른다.

1. abstract (한 줄 요약) — 무엇을 했는지 1문장.
2. 배경/목적 — 왜 이 작업이 필요했는가. 트리거 상황.
3. 절차 — 복붙 가능한 CLI/IaC. 환경변수는 PROFILE, REGION 등으로 상단에 모아둔다.
4. 검증 — 명령 실행 후 성공으로 판정할 수 있는 출력/지표.
5. 롤백 — 잘못됐을 때 되돌리는 정확한 절차.

"함정과 노하우" 섹션은 선택. 비-자명한 실패 케이스가 있으면 꼭 적는다.

2. 파일 위치 규칙

docs/<카테고리>/YYYY-MM-DD-<slug>.md

• 카테고리는 기존 디렉터리(ecs/, s3/, rds/ 등) 중 적합한 곳. 없으면 새로 만들어도 됨.
• 날짜는 작업 수행 날짜 (글 작성 날짜 아님).
• slug는 영문 소문자 + 하이픈.

3. 네비게이션 등록

mkdocs.yml의 nav 항목에 새 글 경로를 추가한다.

nav:
  - ECS:
      - ecs/index.md
      - YYYY-MM-DD 짧은 설명: ecs/YYYY-MM-DD-slug.md   # ← 추가

새 카테고리를 만들었으면 같은 디렉터리에 index.md도 만들고 nav에 추가한다.

4. 로컬 미리보기

pip install -r requirements.txt
mkdocs serve
# → http://127.0.0.1:8000

링크 깨짐/렌더 깨짐을 잡기 위해 mkdocs build --strict가 통과하는지 확인:

mkdocs build --strict

5. 배포

git checkout stag
git pull origin stag
git add docs/<카테고리>/YYYY-MM-DD-slug.md mkdocs.yml
git commit -m "docs(<카테고리>): <한 줄 요약>"
git push origin stag

push 직후:

1. CodePipeline reconlabs-infra-blog-pipeline이 자동 트리거됨.
2. 진행 상황은 AWS Console > CodePipeline 또는:

   aws codepipeline get-pipeline-state \
     --profile oldplicar-kyle --region us-east-1 \
     --name reconlabs-infra-blog-pipeline
   

3. Deploy 단계 끝에서 CloudFront 무효화(/*)가 자동 수행된다. 브라우저 캐시는 즉시 무효화되어 새 글이 바로 보인다.

전체 배포 시간은 보통 3–6분.

6. 에이전트를 위한 체크리스트

AI 에이전트가 이 작업을 수행할 때 확인할 것:

• 파일 경로 규칙 (docs/<cat>/YYYY-MM-DD-slug.md) 준수
• mkdocs.yml의 nav에 등록
• 5섹션 구조 (abstract / 배경 / 절차 / 검증 / 롤백) 준수
• mkdocs build --strict 통과
• stag 브랜치에 push
• push 후 CodePipeline 상태가 Succeeded인지 확인
• 사이트(https://infra.reconlabs.ai)에서 새 글 노출 확인