지식센터 / 레퍼런스

📋 KHub × Asana 기술문서 동기화 전략 — 방안 C (하이브리드)

# 📋 Asana 기술문서 운영 표준 — DESC + 이력댓글 + .md Attachment

> v3.0 | 2026-03-30 | project_code: COMMON

> 검색: khub_search("Asana 기술문서 표준", "COMMON") 또는 khub_search("KHub Asana 동기화", "COMMON")

> 적용 대상: Asana 기술 아키텍처 문서 전체

> 기존: KHub × Asana 동기화 전략 방안 C → v3.0에서 운영 표준으로 확정

---

1. 3종 구조 (필수)

Asana에 기술문서를 작성할 때 반드시 아래 3가지를 모두 수행한다.

[1] DESC (notes)
    = 최신 본문 전체 (plain text)
    = 다른 AI/사람이 태스크만 열면 전체 내용 확인 가능
    = 하단에 KHub 메타 블록 포함
    = REST API: PUT /tasks/{gid} (notes 필드)

[2] 댓글 (stories) — 이력 로그만
    = 변경 이력만 기록. 본문 복붙 절대 금지.
    = 형식: [SYNC v{버전}] YYYY-MM-DD {변경 요약}
    = text 필드만 사용 (html_text 사용 금지 → 태그 raw 노출)
    = REST API: POST /tasks/{gid}/stories (text 필드)

[3] Attachments — .md 파일 물리적 첨부
    = DESC와 동일 내용의 .md 파일을 물리적으로 업로드
    = 파일명: {서비스명}-Tech-Reference.md
    = 다운로드/외부 공유/Google Drive 연동 가능
    = REST API: POST /tasks/{gid}/attachments (multipart/form-data)

2. 실행 순서 (Claude 체크리스트)

신규 작성 시

1. DB 실측 쿼리 (Supabase MCP / n8n relay)
2. .md 파일 작성 (/mnt/user-data/outputs/{서비스명}-Tech-Reference.md)
3. Asana desc 교체: PUT /tasks/{gid} notes=.md 본문
4. Asana .md 첨부: POST /tasks/{gid}/attachments file=.md
5. Asana 이력 댓글: POST /tasks/{gid}/stories text="[SYNC v1.0] ..."
6. 기존 본문복붙 댓글 삭제 (있다면): DELETE /stories/{sid}
7. 진행상태 = 완료 → 섹션 상단 재정렬
8. Quick Memo 업데이트

PGE 검증 후 업데이트 시

1. KHub 업데이트: khub_update_document(doc_id, new_content)
2. .md 파일 재생성 (버전 올림)
3. Asana desc 교체: PUT /tasks/{gid} notes=새 본문+메타블록
4. Asana 새 .md 첨부: POST /tasks/{gid}/attachments file=v{버전}.md
5. Asana 이력 댓글: "[SYNC v{버전}] {변경 요약}"
6. desc 하단 KHub 메타 블록 버전/날짜 갱신

3. DESC 하단 KHub 메타 블록

모든 기술문서 DESC 맨 끝에 이 블록을 넣는다:

--- KHub 동기화 ---
KHub ID: {full_uuid}
KHub 버전: v{버전}
최종 동기화: {YYYY-MM-DD}
동기화 방법: khub_get_document("{8자리}")
project_code: {코드}

4. 이력 댓글 형식

[SYNC v1.0] 2026-03-30 초판 작성
- DB 실측: {소스 DB} 직접 쿼리
- {핵심 내용 3-5줄}
- 첨부: {파일명}.md

[SYNC v2.0] 2026-04-15 검증 반영
- PGE 검증: {Pass/Fail 사항}
- 변경: {수정된 내용}
- 첨부: {파일명}-v2.0.md

5. Attachment 업로드 명령어

ASANA_PAT="$(get from de_admin_credentials)"

# .md 파일 첨부
curl -s -X POST "https://app.asana.com/api/1.0/tasks/{TASK_GID}/attachments" \
  -H "Authorization: Bearer $ASANA_PAT" \
  -F "file=@/mnt/user-data/outputs/{서비스명}-Tech-Reference.md;type=text/markdown" \
  -F "name={서비스명}-Tech-Reference.md"

6. 금지 사항

• 댓글에 본문 전체 복붙 금지 (이력 로그만)
• 댓글에 html_text 필드 사용 금지 (태그 raw 노출)
• Asana에서 직접 desc 수정 금지 (KHub → Asana 단방향)
• .md 파일 없이 desc만 작성 금지 (3종 모두 필수)

7. 커스텀 필드 표준

작업 완료 시 반드시 설정:

• 진행상태(3): 완료 (GID: 1129966517477191)
• 서비스(상품): 해당 서비스 선택
• Quick Memo: 핵심 수치 요약 (예: "577T | 6,383컬럼 | de_data_catalog 통합")
• 완료 태스크는 섹션 상단으로 재정렬

8. 현재 적용 현황

9. Asana 정보

---

v3.0 2026-03-30 — 운영 표준 확정. DESC+이력댓글+.md Attachment 3종 필수. 금지사항 명시.

관련 문서

이 문서를 참조하는 문서 (역링크)

• 없음

다른 표현: Markdown · JSON · 최종 갱신 2026-08-24