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

> # 📋 Asana 기술문서 운영 표준 — DESC + 이력댓글 + .md Attachment > v3.0 | 2026-03-30 | project_code: COMMON > 검색: khub_search("Asana 기술문서 표준", "COMMON") 또는 khub_search("KH

## 핵심 요약


# 📋 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 업로드 명령어

```bash
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. 현재 적용 현황

| 태스크 | DESC | 이력댓글 | .md 첨부 | 상태 |
|--------|------|---------|---------|------|
| [ARCH] 통합 설계서 v3.0 | ✅ | ✅ | ✅ bizspring-de-admin-design-v3.0.md | 완료 |
| [ARCH] Data Catalog | ✅ | ✅ | ✅ BizSpring-Data-Catalog-v1.1.md | 완료 |
| [GEOcare™] | ✅ | ✅ | ✅ GEOcare-AI-Tech-Reference.md | 완료 |
| [TAM™/DMP] | ✅ | ✅ | ✅ DMP-RunComm-Tech-Reference.md | 완료 |
| [DIGO™] | ✅ | ✅ | ✅ DIGO-Influencer-Tech-Reference.md | 완료 |
| [FeedMaker™] | ✅ | ✅ | ✅ FeedMaker-Tech-Reference.md | 완료 |
| [LIFT™] | ✅ | ✅ | ✅ LIFT-Tracker-Tech-Reference.md | 완료 |
| [ARCH] GP MySQL 계정 | ✅ | ✅ | ⏳ 향후 | 완료 |
| [ARCH] GitHub 매핑 | ✅ | ✅ | ⏳ 향후 | 완료 |
| [VERIFY] DB 검증 | ✅ | ✅ | ⏳ 향후 | 완료 |

## 9. Asana 정보

| 항목 | 값 |
|------|-----|
| 프로젝트 | 제품/기능 기획(PRODUCT OWNER) / GID: 1200220022474171 |
| 섹션 | 기술 아키텍처 문서 w/AI v202603 / GID: 1213858749160371 |
| PAT | de_admin_credentials service_name='ASANA_API_KEY' |

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

## FAQ


---
출처: https://bizspring.ai/kb/ref/khub/common-khub-asana-기술문서-동기화-전략-방안-c-하이브리드 · 최종 갱신 2026-08-24T11:53:44.908861+00:00