{
  "id": "88475c86-caa9-4465-a28c-2a7bd7f137b3",
  "slug": "ref/khub/common-khub-asana-기술문서-동기화-전략-방안-c-하이브리드",
  "doc_type": "ref",
  "title": "📋 KHub × Asana 기술문서 동기화 전략 — 방안 C (하이브리드)",
  "title_en": null,
  "one_liner": "# 📋 Asana 기술문서 운영 표준 — DESC + 이력댓글 + .md Attachment > v3.0 | 2026-03-30 | project_code: COMMON > 검색: khub_search(\"Asana 기술문서 표준\", \"COMMON\") 또는 khub_search(\"KH",
  "summary_bullets": [],
  "body_md": "# 📋 Asana 기술문서 운영 표준 — DESC + 이력댓글 + .md Attachment\n\n> v3.0 | 2026-03-30 | project_code: COMMON\n> 검색: khub_search(\"Asana 기술문서 표준\", \"COMMON\") 또는 khub_search(\"KHub Asana 동기화\", \"COMMON\")\n> 적용 대상: Asana 기술 아키텍처 문서 전체\n> 기존: KHub × Asana 동기화 전략 방안 C → v3.0에서 운영 표준으로 확정\n\n---\n\n## 1. 3종 구조 (필수)\n\nAsana에 기술문서를 작성할 때 반드시 아래 3가지를 모두 수행한다.\n\n```\n[1] DESC (notes)\n    = 최신 본문 전체 (plain text)\n    = 다른 AI/사람이 태스크만 열면 전체 내용 확인 가능\n    = 하단에 KHub 메타 블록 포함\n    = REST API: PUT /tasks/{gid} (notes 필드)\n\n[2] 댓글 (stories) — 이력 로그만\n    = 변경 이력만 기록. 본문 복붙 절대 금지.\n    = 형식: [SYNC v{버전}] YYYY-MM-DD {변경 요약}\n    = text 필드만 사용 (html_text 사용 금지 → 태그 raw 노출)\n    = REST API: POST /tasks/{gid}/stories (text 필드)\n\n[3] Attachments — .md 파일 물리적 첨부\n    = DESC와 동일 내용의 .md 파일을 물리적으로 업로드\n    = 파일명: {서비스명}-Tech-Reference.md\n    = 다운로드/외부 공유/Google Drive 연동 가능\n    = REST API: POST /tasks/{gid}/attachments (multipart/form-data)\n```\n\n## 2. 실행 순서 (Claude 체크리스트)\n\n### 신규 작성 시\n\n```\n1. DB 실측 쿼리 (Supabase MCP / n8n relay)\n2. .md 파일 작성 (/mnt/user-data/outputs/{서비스명}-Tech-Reference.md)\n3. Asana desc 교체: PUT /tasks/{gid} notes=.md 본문\n4. Asana .md 첨부: POST /tasks/{gid}/attachments file=.md\n5. Asana 이력 댓글: POST /tasks/{gid}/stories text=\"[SYNC v1.0] ...\"\n6. 기존 본문복붙 댓글 삭제 (있다면): DELETE /stories/{sid}\n7. 진행상태 = 완료 → 섹션 상단 재정렬\n8. Quick Memo 업데이트\n```\n\n### PGE 검증 후 업데이트 시\n\n```\n1. KHub 업데이트: khub_update_document(doc_id, new_content)\n2. .md 파일 재생성 (버전 올림)\n3. Asana desc 교체: PUT /tasks/{gid} notes=새 본문+메타블록\n4. Asana 새 .md 첨부: POST /tasks/{gid}/attachments file=v{버전}.md\n5. Asana 이력 댓글: \"[SYNC v{버전}] {변경 요약}\"\n6. desc 하단 KHub 메타 블록 버전/날짜 갱신\n```\n\n## 3. DESC 하단 KHub 메타 블록\n\n모든 기술문서 DESC 맨 끝에 이 블록을 넣는다:\n\n```\n--- KHub 동기화 ---\nKHub ID: {full_uuid}\nKHub 버전: v{버전}\n최종 동기화: {YYYY-MM-DD}\n동기화 방법: khub_get_document(\"{8자리}\")\nproject_code: {코드}\n```\n\n## 4. 이력 댓글 형식\n\n```\n[SYNC v1.0] 2026-03-30 초판 작성\n- DB 실측: {소스 DB} 직접 쿼리\n- {핵심 내용 3-5줄}\n- 첨부: {파일명}.md\n\n[SYNC v2.0] 2026-04-15 검증 반영\n- PGE 검증: {Pass/Fail 사항}\n- 변경: {수정된 내용}\n- 첨부: {파일명}-v2.0.md\n```\n\n## 5. Attachment 업로드 명령어\n\n```bash\nASANA_PAT=\"$(get from de_admin_credentials)\"\n\n# .md 파일 첨부\ncurl -s -X POST \"https://app.asana.com/api/1.0/tasks/{TASK_GID}/attachments\" \\\n  -H \"Authorization: Bearer $ASANA_PAT\" \\\n  -F \"file=@/mnt/user-data/outputs/{서비스명}-Tech-Reference.md;type=text/markdown\" \\\n  -F \"name={서비스명}-Tech-Reference.md\"\n```\n\n## 6. 금지 사항\n\n- 댓글에 본문 전체 복붙 금지 (이력 로그만)\n- 댓글에 html_text 필드 사용 금지 (태그 raw 노출)\n- Asana에서 직접 desc 수정 금지 (KHub → Asana 단방향)\n- .md 파일 없이 desc만 작성 금지 (3종 모두 필수)\n\n## 7. 커스텀 필드 표준\n\n작업 완료 시 반드시 설정:\n- 진행상태(3): 완료 (GID: 1129966517477191)\n- 서비스(상품): 해당 서비스 선택\n- Quick Memo: 핵심 수치 요약 (예: \"577T | 6,383컬럼 | de_data_catalog 통합\")\n- 완료 태스크는 섹션 상단으로 재정렬\n\n## 8. 현재 적용 현황\n\n| 태스크 | DESC | 이력댓글 | .md 첨부 | 상태 |\n|--------|------|---------|---------|------|\n| [ARCH] 통합 설계서 v3.0 | ✅ | ✅ | ✅ bizspring-de-admin-design-v3.0.md | 완료 |\n| [ARCH] Data Catalog | ✅ | ✅ | ✅ BizSpring-Data-Catalog-v1.1.md | 완료 |\n| [GEOcare™] | ✅ | ✅ | ✅ GEOcare-AI-Tech-Reference.md | 완료 |\n| [TAM™/DMP] | ✅ | ✅ | ✅ DMP-RunComm-Tech-Reference.md | 완료 |\n| [DIGO™] | ✅ | ✅ | ✅ DIGO-Influencer-Tech-Reference.md | 완료 |\n| [FeedMaker™] | ✅ | ✅ | ✅ FeedMaker-Tech-Reference.md | 완료 |\n| [LIFT™] | ✅ | ✅ | ✅ LIFT-Tracker-Tech-Reference.md | 완료 |\n| [ARCH] GP MySQL 계정 | ✅ | ✅ | ⏳ 향후 | 완료 |\n| [ARCH] GitHub 매핑 | ✅ | ✅ | ⏳ 향후 | 완료 |\n| [VERIFY] DB 검증 | ✅ | ✅ | ⏳ 향후 | 완료 |\n\n## 9. Asana 정보\n\n| 항목 | 값 |\n|------|-----|\n| 프로젝트 | 제품/기능 기획(PRODUCT OWNER) / GID: 1200220022474171 |\n| 섹션 | 기술 아키텍처 문서 w/AI v202603 / GID: 1213858749160371 |\n| PAT | de_admin_credentials service_name='ASANA_API_KEY' |\n\n---\nv3.0 2026-03-30 — 운영 표준 확정. DESC+이력댓글+.md Attachment 3종 필수. 금지사항 명시.",
  "related_slugs": [],
  "faq": [],
  "jsonld": null,
  "keywords": [],
  "source_id": "7a992fbf-fb85-4a27-b816-d49b9dad2c48",
  "video_url": null,
  "duration_sec": null,
  "thumbnail_url": null,
  "image_url": null,
  "caption": null,
  "solution_slug": null,
  "captured_at": null,
  "width": null,
  "height": null,
  "created_at": "2026-08-24T11:53:44.908861+00:00",
  "updated_at": "2026-08-24T11:53:44.908861+00:00",
  "visibility": "public",
  "source_stage": "1",
  "anonymized": true,
  "source_key": "legacy-khub",
  "origin": "ingest",
  "locked": false,
  "locked_by": null,
  "locked_at": null,
  "gate_state": {
    "g1": {
      "hits": [],
      "pass": true
    },
    "g2": {
      "pass": true,
      "total": 38,
      "issues": [
        "숫자·규격 같은 검증 가능한 구체가 부족합니다",
        "다른 문서와 겹치는 말이 대부분입니다",
        "핵심 요약 불릿이 3개 미만입니다",
        "Q&A 쌍이 3개 미만입니다"
      ],
      "applies": true
    },
    "g3": {
      "pass": true,
      "required": false
    },
    "stage": "1",
    "decided_at": "2026-08-24T11:53:44.334Z"
  },
  "raw_id": "7e3fad5f-551e-41e7-9529-4d6c8faa698b",
  "search_text": "📋 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\n\n> v3.0 | 2026-03-30 | project_code: COMMON\n> 검색: khub_search(\"Asana 기술문서 표준\", \"COMMON\") 또는 khub_search(\"KHub Asana 동기화\", \"COMMON\")\n> 적용 대상: Asana 기술 아키텍처 문서 전체\n> 기존: KHub × Asana 동기화 전략 방안 C → v3.0에서 운영 표준으로 확정\n\n---\n\n## 1. 3종 구조 (필수)\n\nAsana에 기술문서를 작성할 때 반드시 아래 3가지를 모두 수행한다.\n\n```\n[1] DESC (notes)\n    = 최신 본문 전체 (plain text)\n    = 다른 AI/사람이 태스크만 열면 전체 내용 확인 가능\n    = 하단에 KHub 메타 블록 포함\n    = REST API: PUT /tasks/{gid} (notes 필드)\n\n[2] 댓글 (stories) — 이력 로그만\n    = 변경 이력만 기록. 본문 복붙 절대 금지.\n    = 형식: [SYNC v{버전}] YYYY-MM-DD {변경 요약}\n    = text 필드만 사용 (html_text 사용 금지 → 태그 raw 노출)\n    = REST API: POST /tasks/{gid}/stories (text 필드)\n\n[3] Attachments — .md 파일 물리적 첨부\n    = DESC와 동일 내용의 .md 파일을 물리적으로 업로드\n    = 파일명: {서비스명}-Tech-Reference.md\n    = 다운로드/외부 공유/Google Drive 연동 가능\n    = REST API: POST /tasks/{gid}/attachments (multipart/form-data)\n```\n\n## 2. 실행 순서 (Claude 체크리스트)\n\n### 신규 작성 시\n\n```\n1. DB 실측 쿼리 (Supabase MCP / n8n relay)\n2. .md 파일 작성 (/mnt/user-data/outputs/{서비스명}-Tech-Reference.md)\n3. Asana desc 교체: PUT /tasks/{gid} notes=.md 본문\n4. Asana .md 첨부: POST /tasks/{gid}/attachments file=.md\n5. Asana 이력 댓글: POST /tasks/{gid}/stories text=\"[SYNC v1.0] ...\"\n6. 기존 본문복붙 댓글 삭제 (있다면): DELETE /stories/{sid}\n7. 진행상태 = 완료 → 섹션 상단 재정렬\n8. Quick Memo 업데이트\n```\n\n### PGE 검증 후 업데이트 시\n\n```\n1. KHub 업데이트: khub_update_document(doc_id, new_content)\n2. .md 파일 재생성 (버전 올림)\n3. Asana desc 교체: PUT /tasks/{gid} notes=새 본문+메타블록\n4. Asana 새 .md 첨부: POST /tasks/{gid}/attachments file=v{버전}.md\n5. Asana 이력 댓글: \"[SYNC v{버전}] {변경 요약}\"\n6. desc 하단 KHub 메타 블록 버전/날짜 갱신\n```\n\n## 3. DESC 하단 KHub 메타 블록\n\n모든 기술문서 DESC 맨 끝에 이 블록을 넣는다:\n\n```\n--- KHub 동기화 ---\nKHub ID: {full_uuid}\nKHub 버전: v{버전}\n최종 동기화: {YYYY-MM-DD}\n동기화 방법: khub_get_document(\"{8자리}\")\nproject_code: {코드}\n```\n\n## 4. 이력 댓글 형식\n\n```\n[SYNC v1.0] 2026-03-30 초판 작성\n- DB 실측: {소스 DB} 직접 쿼리\n- {핵심 내용 3-5줄}\n- 첨부: {파일명}.md\n\n[SYNC v2.0] 2026-04-15 검증 반영\n- PGE 검증: {Pass/Fail 사항}\n- 변경: {수정된 내용}\n- 첨부: {파일명}-v2.0.md\n```\n\n## 5. Attachment 업로드 명령어\n\n```bash\nASANA_PAT=\"$(get from de_admin_credentials)\"\n\n# .md 파일 첨부\ncurl -s -X POST \"https://app.asana.com/api/1.0/tasks/{TASK_GID}/attachments\" \\\n  -H \"Authorization: Bearer $ASANA_PAT\" \\\n  -F \"file=@/mnt/user-data/outputs/{서비스명}-Tech-Reference.md;type=text/markdown\" \\\n  -F \"name={서비스명}-Tech-Reference.md\"\n```\n\n## 6. 금지 사항\n\n- 댓글에 본문 전체 복붙 금지 (이력 로그만)\n- 댓글에 html_text 필드 사용 금지 (태그 raw 노출)\n- Asana에서 직접 desc 수정 금지 (KHub → Asana 단방향)\n- .md 파일 없이 desc만 작성 금지 (3종 모두 필수)\n\n## 7. 커스텀 필드 표준\n\n작업 완료 시 반드시 설정:\n- 진행상태(3): 완료 (GID: 1129966517477191)\n- 서비스(상품): 해당 서비스 선택\n- Quick Memo: 핵심 수치 요약 (예: \"577T | 6,383컬럼 | de_data_catalog 통합\")\n- 완료 태스크는 섹션 상단으로 재정렬\n\n## 8. 현재 적용 현황\n\n| 태스크 | DESC | 이력댓글 | .md 첨부 | 상태 |\n|--------|------|---------|---------|------|\n| [ARCH] 통합 설계서 v3.0 | ✅ | ✅ | ✅ bizspring-de-admin-design-v3.0.md | 완료 |\n| [ARCH] Data Catalog | ✅ | ✅ | ✅ BizSpring-Data-Catalog-v1.1.md | 완료 |\n| [GEOcare™] | ✅ | ✅ | ✅ GEOcare-AI-Tech-Reference.md | 완료 |\n| [TAM™/DMP] | ✅ | ✅ | ✅ DMP-RunComm-Tech-Reference.md | 완료 |\n| [DIGO™] | ✅ | ✅ | ✅ DIGO-Influencer-Tech-Reference.md | 완료 |\n| [FeedMaker™] | ✅ | ✅ | ✅ FeedMaker-Tech-Reference.md | 완료 |\n| [LIFT™] | ✅ | ✅ | ✅ LIFT-Tracker-Tech-Reference.md | 완료 |\n| [ARCH] GP MySQL 계정 | ✅ | ✅ | ⏳ 향후 | 완료 |\n| [ARCH] GitHub 매핑 | ✅ | ✅ | ⏳ 향후 | 완료 |\n| [VERIFY] DB 검증 | ✅ | ✅ | ⏳ 향후 | 완료 |\n\n## 9. Asana 정보\n\n| 항목 | 값 |\n|------|-----|\n| 프로젝트 | 제품/기능 기획(PRODUCT OWNER) / GID: 1200220022474171 |\n| 섹션 | 기술 아키텍처 문서 w/AI v202603 / GID: 1213858749160371 |\n| PAT | de_admin_credentials service_name='ASANA_API_KEY' |\n\n---\nv3.0 2026-03-30 — 운영 표준 확정. DESC+이력댓글+.md Attachment 3종 필수. 금지사항 명시.",
  "embedding": null,
  "embedded_at": null,
  "embedding_hash": null,
  "backlinks": [],
  "html_url": "https://bizspring.ai/kb/ref/khub/common-khub-asana-기술문서-동기화-전략-방안-c-하이브리드",
  "markdown_url": "https://bizspring.ai/kb/ref/khub/common-khub-asana-기술문서-동기화-전략-방안-c-하이브리드.md"
}