카드: 기억을 한 장으로 꺼내 공유하기

AI에게 시켜 만드는 한 장짜리 공개 페이지. 만드는 순간 공개되고, 관리는 콘솔에서 한다.

AiAkiv에 쌓인 기억은 나만 본다. 남에게 보여주려면 매번 복사해 옮겨 붙여야 했다. 카드는 그 사이를 잇는다. AI에게 "이 주제로 카드 만들어줘"라고 하면 내 기억을 정리한 공개 페이지 한 장이 만들어지고, 주소 하나가 나온다. 그 주소를 카카오톡·슬랙·블로그 어디에 붙여도 카드 모양으로 펼쳐진다.

한 줄 요약. 카드는 AI가 내 기억에서 써 주는 한 장짜리 공개 페이지다. 만드는 순간부터 웹에 올라가고, 주소를 아는 사람은 로그인 없이 본다. 관리(주소 복사·이미지·삭제·검색 노출)는 콘솔 → 데이터 → 카드에서 한다.

이 문서는 사람과 AI가 같이 읽는다. §1~§7은 사람용, §8은 AI용이다. AI는 §8을 먼저 읽어도 되지만 §5(꼭 알아야 할 것)는 반드시 함께 읽는다.


1. 카드가 무엇인가

카드 한 장에는 이런 것이 담긴다.

항목 내용 어디에 보이나
제목 한 줄 페이지·이미지·링크 미리보기
요약 핵심 3~5줄 페이지·이미지
결론 한 문장 페이지·이미지·링크 미리보기 설명
태그 최대 3개 페이지·이미지 하단·검색
본문 (선택) 제대로 된 글 한 편(마크다운) 페이지에만
출처 수 "기억 N건에서" 이미지 하단

받는 사람은 AiAkiv 회원일 필요가 없다. 로그인도 없다. 그냥 웹페이지 하나다. 카드 페이지와 함께 이미지 두 장(가로형·정사각)이 같이 만들어지고, 이미지 안에 카드 주소가 새겨져 있다.

주소는 이렇게 짧다.

https://card.aiakiv.com/kx7mabcd23

일부러 10자로 짧게 만들었다. 인스타그램처럼 링크를 못 누르는 곳에서는 사람이 화면을 보고 손으로 옮겨 적어야 하기 때문이다. 헷갈리는 글자(i l o 0 1)는 아예 쓰지 않는다.

카드와 본문의 역할

카드만 있으면 링크를 눌러 들어가도 미리보기에서 이미 본 요약이 그대로다. 클릭할 이유가 없다. 본문이 붙어야 카드가 들어가는 입구가 되고 페이지가 읽을 거리가 된다. 그래서 읽는 순서는 요약 → 본문 → 결론이다. 본문이 없으면 카드만 있는 것과 똑같이 동작한다.

"블로그"가 아니다. 글 목록도, 댓글도, 구독도, 작성자 프로필도 없다. 한 장씩 만들어 한 장씩 공유하는 것까지가 이 기능의 몫이다.


2. 만들기: AI에게 시킨다

카드는 AI를 통해서만 만든다. 콘솔에는 만들기 버튼이 없다. 내용을 정리하는 것은 AI의 일이고, 콘솔은 만들어진 것을 관리하는 곳이다.

AiAkiv를 연결해 둔 AI(Claude, ChatGPT, Codex, Gemini 등)에게 이렇게 말한다.

"메모리에서 〈주제〉 찾아서 카드로 만들어줘. 본문도 같이 써줘."

AI가 하는 일은 셋이다.

  1. 내 기억을 검색해서 그 주제의 내용을 모은다
  2. 제목·요약·결론(·본문)을 직접 쓴다: 요약은 AI가 쓰고, 서버는 글을 손대지 않는다
  3. 카드 서비스에 넘겨 굽는다 → 주소가 돌아온다

무엇을 담을지는 사람이 정한다. 어떻게 정리할지는 AI가 한다. 마음에 안 들면 다시 시키면 된다(다만 §5의 "다시 만들면 새 카드"를 읽어 둘 것).

잘 시키는 법

  • 주제를 좁게. "AiAkiv 전체 소개"보다 "AiAkiv가 왜 그래프인가"가 좋은 카드가 된다. 요약이 3~5줄뿐이라 넓은 주제는 흐려진다.
  • 본문 여부를 말한다. "본문도 써줘" / "카드만". 본문이 있어야 링크를 누를 이유가 생긴다.
  • 검색어를 정해 준다. 태그가 곧 검색어다(§4). "태그는 메모리그래프, 팀공유로" 처럼 정해 주면 나중에 card.aiakiv.com에서 그 말로 찾을 수 있다.
  • 공개 메모리로도 만들 수 있다. 아직 내 기억이 없어도, 읽을 수 있는 공개 기억으로 카드를 만들 수 있다.
  • 만들기 전에 초안을 보고 싶으면 "먼저 내용만 보여줘"라고 한다. AI가 초안을 보여주고 확인 후 만들게 할 수 있다. 만드는 순간 공개되므로(§5) 민감한 주제일수록 이 한 단계가 값어치를 한다.

만들고 나면 이런 것이 온다

  • 공개됐다는 안내: AI가 가장 먼저 말해 준다("이 카드는 이미 웹에 올라가 있습니다 …"). 형식적인 문구가 아니라 지금 상태 그대로다
  • 주소: https://card.aiakiv.com/…… 10자
  • 이미지 주소 두 개: 가로형(…/og.png)과 정사각(…/square.png)
  • (있으면) 잘림 안내: 요약이 길어 이미지에서 잘렸다면 어느 줄이 잘렸는지 AI가 알려 준다. 그러면 줄여서 다시 만들지, 그대로 둘지 정한다

3. 붙이기: 어디에 어떻게 보이나

어디 어떻게 하나 어떻게 보이나
카카오톡, 슬랙, 디스코드, 텔레그램 주소만 붙여넣기 카드 모양으로 자동으로 펼쳐진다
네이버 블로그·카페, 티스토리, 노션 주소만 붙여넣기 같음
페이스북, 링크드인, X, 레딧 주소만 붙여넣기 같음
워드프레스, 노션 임베드 주소 붙여넣기 카드 페이지가 안에 살아 들어간다
인스타그램 이미지를 올리고 캡션에 주소를 적는다 이미지로 보인다
일부 커뮤니티 게시판 주소를 붙이거나, 안 펼쳐지면 이미지를 올린다 게시판마다 다르다

이미지는 어디서 받나

콘솔 → 데이터 → 카드에서 카드마다 이미지 › 정사각 / 가로형 링크가 있다. 새 탭에서 열리니 거기서 저장한다. AI가 만들 때 준 이미지 주소를 열어도 같다.

  • 정사각: 인스타그램용. 하단 한 줄에 주소와 검색어가 또렷하게 들어 있다
  • 가로형: 게시판·블로그용. 링크 미리보기에 쓰이는 것과 같은 그림이다

이미지 안에 주소가 새겨져 있어서, 링크가 안 되는 곳에서도 보는 사람이 카드로 돌아올 길이 있다. 요즘 폰은 사진 속 글자를 눌러 복사할 수 있어 그 길이 생각보다 넓다.

알아둘 것: 펼쳐진 카드는 통째로 하나의 링크다

카카오톡·슬랙이 펼쳐 주는 카드는 그쪽 서비스가 우리 정보를 읽어 자기 방식으로 다시 그린 것이다. 카드 안의 글자를 따로 누를 수는 없고, 어디를 눌러도 카드 페이지로 간다. 본문에 넣은 링크는 페이지에 들어간 뒤에 눌린다. 결함이 아니라 의도한 흐름이다. 미리보기로 눈길을 끌고, 눌러서 들어오게 하고, 본문을 읽게 한다.

미리보기 지원 여부는 서비스마다 다르고 개편 때 바뀐다. 처음 붙이는 곳이면 한 번 확인하고 쓰는 것이 확실하다.


4. 관리: 콘솔에서

콘솔(app.aiakiv.com) → 데이터 → 카드.

할 수 있는 것 설명
목록 내가 만든 카드. 제목·만든 날·검색 노출 여부
주소 복사 카드 주소를 클립보드로
이미지 정사각 / 가로형을 새 탭에서 연다 → 저장해서 올린다
삭제 한 번 확인 후 지운다. 되돌릴 수 없다
검색 노출 켜고 끈다. 기본은 꺼짐
공개 닉네임 검색 결과에 작성자로 나올 이름. 안 정하면 자동으로 붙는다
분류 태그 내가 직접 만드는 분류. 카드에 붙였다 뗐다 한다

목록 맨 위에는 항상 같은 안내가 떠 있다. "여기 있는 카드는 이미 공개돼 있다." 그리고 접히는 카드 만드는 법 안내(복사용 프롬프트, 형식 한도)가 있다.

검색 노출: 오해하기 쉬운 항목

검색을 꺼 둬도 카드는 공개돼 있다. 껐다는 것은 "찾아지지 않는다"는 뜻이지 "안 보인다"는 뜻이 아니다. 주소를 아는 사람은 언제든 본다.

검색을 켜면 거기에 더해 card.aiakiv.com에서 누구나 찾을 수 있게 된다. 검색은 제목과 태그로 한다. 슬랙 채널 하나에 공유하려고 만든 카드가 모르는 사람의 검색 결과에 뜨는 것은 만든 사람이 기대한 "공개"가 아니라서, 기본은 꺼져 있고 명시적으로 켜야 한다. 껐다 켰다 할 수 있으니 나중에 정해도 된다.

켜고 끄는 것은 콘솔에서만 한다. AI에게 "검색에 나오게 해 줘"라고 해도 AI는 못 한다. 만들 때 정할 일이 아니라 나중에 마음이 바뀌는 설정이라 그렇게 두었다.

공개 닉네임: "이 사람 카드 모아 보기"의 이름

검색 결과에는 내 카드의 작성자로 닉네임이 붙는다. 누르면 내 카드만 모아서 보이고, 그 화면 주소를 그대로 공유할 수 있다.

  • 안 정해도 이름은 붙는다. 첫 카드를 만들 때 anonymous-473812 같은 이름이 자동으로 생긴다. 이름이 없으면 검색에서 작성자별로 묶이지 않기 때문이다. 마음에 안 들면 콘솔에서 바꾸면 된다
  • 번호는 순번이 아니라 무작위다. 순번이면 anonymous-7 을 본 사람이 사용자가 일곱 명이라는 것까지 알게 된다
  • anonymous-… 모양을 직접 정할 수는 없다. 아직 안 쓰인 번호를 미리 차지하면 나중에 그 번호를 받을 사람의 자리를 막기 때문이다
  • 이름이 나가는 곳은 검색 목록뿐이다. 카드 페이지에는 작성자가 안 나온다. 그러니 검색 노출을 켠 카드에만 이름이 따라간다
  • 이메일은 어떤 경우에도 공개되지 않는다. 검색 목록 파일은 로그인 없이 누구나 받을 수 있어서, 거기에 사람을 가리키는 값으로 실리는 것은 닉네임뿐이다
  • 언어 제한이 없다. 한글·일본어·아랍어 다 된다. 2~20자, 공백은 빠진다
  • 먼저 정한 사람이 임자다. 이미 쓰이는 이름은 못 쓴다
  • 비우고 저장하면 내려간다. 다만 다음에 카드를 만들면 자동 이름이 다시 붙는다
  • ⚠ 이름을 바꾸면 그 이름으로 공유해 둔 "모아 보기" 주소가 끊긴다. 카드 주소는 영향받지 않는다

분류 태그: 내가 직접 만드는 분류

카드에 붙는 태그가 두 종류라 헷갈리기 쉽다. 다른 것이다.

누가 붙이나 어디에 보이나 고칠 수 있나
카드 태그 AI가 만들 때 카드 이미지와 페이지 아래 ✗ 이미지에 새겨져 있다
분류 태그 내가 콘솔에서 카드 페이지와 검색 ✓ 언제든

쓰는 법은 두 단계다.

  1. 분류를 만든다: 콘솔 카드 화면 위쪽에서 설계, 회고 처럼 태그를 만든다 (50개까지)
  2. 카드에 붙인다: 카드 옆 분류 버튼을 눌러 만들어 둔 것 중에서 고른다 (카드당 5개까지)

붙인 태그는 카드 페이지 아래에 뜨고, 누르면 같은 태그가 붙은 카드가 모여 보인다. 카드 이미지는 바뀌지 않는다: 태그를 고쳤다고 이미 퍼뜨린 그림이 달라지면 안 되기 때문이다.

분류를 지워도 이미 붙은 카드에서는 안 빠진다. 그 카드의 분류 편집에서 직접 떼면 된다. (지울 때마다 카드를 전부 다시 만들면 카드가 많은 사람은 한참 기다려야 한다. 대신 "새로 붙이는 건 만들어 둔 것만, 이미 붙은 건 언제든 뗄 수 있게" 로 두었다.)

찾는 방법은 셋: 그리고 화면이 곧 주소다

card.aiakiv.com에는 칸이 셋이다. 섞어 쓸 수 있다.

무엇을 맞추나
검색어 제목과 카드 태그에 그 글자가 들어간 것
만든 사람 그 닉네임의 카드
분류 태그 그 분류에 든 카드

좁힐 때마다 주소창이 따라 바뀐다. 따로 "고정" 버튼을 누를 필요가 없다. 지금 보이는 화면의 주소를 복사해 보내면 상대도 똑같은 화면을 본다. 화면 안의 이 화면 주소 복사 버튼이 같은 일을 한 번에 해 준다.


5. 꼭 알아야 할 것

만드는 순간부터 공개다

카드는 만들어진 그 순간 이미 웹에 올라가 있고, 주소를 아는 사람은 로그인 없이 본다. 주소를 붙이는 것은 "찾아지게 되는" 일이지 "공개되는" 일이 아니다.

주소가 추측하기 어렵게 만들어져 있어 실제로는 본인만 알 뿐, "비공개"인 것은 아니다. 이 차이가 중요해서 AI가 카드를 만들면 그 자리에서 공개됐다고 알려 주고, 콘솔 카드 화면 맨 위에도 같은 말이 항상 떠 있다.

그래서 개인적인 내용, 아직 공개하면 안 되는 정보, 남의 이름·이메일이 들어가지 않았는지 만들고 나서 한 번 읽어 보는 것이 좋다. AI가 내 기억에서 뽑아 쓰기 때문에 의도치 않은 것이 섞일 수 있다. 민감한 주제면 만들기 전에 초안을 먼저 보라고 하는 편이 낫다(§2).

지우면 페이지는 바로 사라진다: 단, 캐시는 남을 수 있다

  • 카드를 지우면 페이지와 이미지는 즉시 내려간다. 되돌릴 수 없다
  • 다만 카카오톡·슬랙 같은 곳이 미리 저장해 둔 미리보기 캐시는 한동안 남을 수 있다. 그쪽 서비스가 갖고 있는 것이라 우리가 지울 수 없다
  • 이미 본 사람이 저장해 둔 것은 어쩔 수 없다

"공개는 되돌릴 수 없다"는 말이 바로 이 뜻이다.

다시 만들면 새 카드다

"내용을 고쳐 줘"라고 하면 AI는 새 카드를 만든다. 이전 카드는 그대로 공개돼 있고 보유 개수에도 잡힌다. 고친 뒤에는 이전 것을 콘솔에서 지워야 한다. AI가 "이전 카드를 지우세요"라고 안내하는 이유다(AI는 삭제를 못 한다).

지금은 "카드 수정" 기능이 없다. 그래서 목표는 한 번에 맞추는 것이다.

요약은 잘릴 수 있다

요약 3~5줄은 이미지 안의 정해진 세로 공간을 나눠 쓴다. 그래서 다섯 줄을 전부 길게 쓰면 한 줄 글자 수 한도를 지켜도 이미지에서 잘린다. 잘리면 AI가 알려 준다("3번·5번이 잘렸다, 몇 자로 줄여라"). 그러면 줄여서 다시 만들거나(=새 카드), 그대로 둔다. 페이지에는 전문이 다 보이고 잘리는 것은 이미지다.

계정을 지워도 카드는 남는다

탈퇴한다고 이미 공유한 카드가 자동으로 사라지지는 않는다. 남이 붙여 둔 링크가 갑자기 죽는 것을 막기 위해서다. 카드에는 만든 사람의 이름·이메일·원본 기억이 전혀 들어 있지 않아 익명이기도 하다. 지우고 싶으면 탈퇴 전에 콘솔에서 정리하면 되고, 이미 탈퇴했는데 내려야 할 카드가 있으면 운영자([email protected])에게 요청하면 된다.

한도

항목 한도
보유 계정당 50장. 넘으면 지우고 만든다
만드는 속도 시간당 10장, 하루 30장
제목 80자
요약 3~5줄, 각 120자 (이미지에서 다 보이는 안전선은 훨씬 짧다: §8)
결론 200자
태그 3개, 각 20자
본문 3만 자, 제한된 마크다운

한도를 두는 이유는 비용이 아니라 남용이다. 공개 도메인이 낙서장이 되는 것을 막는다. 값은 잠정이며 실사용을 보고 조정한다.


6. 전체적으로 어떻게 동작하나

[사람]  "〈주제〉로 카드 만들어줘"
   │
[AI]    ① 내 기억을 검색한다 (내 권한 그대로)
        ② 제목·요약·결론·본문을 쓴다  ← 글은 AI가 쓴다
        ③ AiAkiv 에 "card 앱에 이걸 만들어 줘" 하고 넘긴다
   │
[AiAkiv]④ 누가 만드는지 확인 · 짧은 주소 발급 · "누구 것"인지만 기록
        ⑤ 카드 서비스에 전달
   │
[카드 서비스] ⑥ 형식 검사(길이·개수)만 한다. 내용은 판단하지 않는다
              ⑦ 페이지 HTML + 이미지 2장을 정해진 틀로 굽는다
              ⑧ 공개 저장소에 올린다
   │
[AI]    ⑨ "공개됐다" 안내 + 주소를 사람에게 보여 준다
   │
[아무나] 주소로 접속 → 저장소가 페이지를 그대로 돌려준다 (로그인·코드 없음)

이 흐름에서 알아 둘 성질들:

  • AI가 쓰고, 서버는 쓰지 않는다. 카드 서비스는 AI 모델을 부르지 않는다. 그래서 요약의 품질은 내가 쓰는 AI의 품질이고, 마음에 안 들면 AI에게 다시 시키는 것이 맞다. 콘솔에 "AI 요약" 버튼이 없는 이유다.
  • 서버가 굽는다. AI는 카드 데이터(제목·요약…)만 보낸다. HTML과 이미지는 반드시 서버가 정해진 틀로 만든다. 그래서 카드 페이지에 임의의 코드가 실릴 수 없고, 나중에 디자인을 바꾸면 이미 만든 카드도 새 모양으로 다시 구울 수 있다.
  • 원본 기억과 끊겨 있다. 카드에는 원본 기억을 가리키는 참조가 없다. 자기 완결적인 스냅샷이다. 원본을 지워도 카드는 남고, 카드는 따로 지운다. 반대로 카드를 지워도 기억은 그대로다.
  • 공개 경로에는 코드가 없다. 카드 페이지는 공개 저장소가 그대로 돌려준다. 그 사이에 로그인도, 데이터베이스도, 서버 코드도 없다. 그래서 공개 페이지가 뚫려도 유출될 것은 "이미 공개된 카드들"뿐이다.
  • 누가 만들었는지는 공개되지 않는다. 소유권은 AiAkiv 안에만 기록되고 카드 주소·페이지·이미지 어디에도 계정 정보가 없다. 다만 주소 앞 4자가 같은 카드는 같은 사람 것이라는 사실은 드러난다(한 사람의 카드를 운영자가 한 번에 정리할 수 있게 하기 위한 구조다).
  • 링크 미리보기는 표준 방식이다. 카드 페이지에 Open Graph 메타(제목·설명· 이미지)와 oEmbed가 들어 있다. 카카오톡·슬랙·노션은 이것을 읽어 카드를 펼친다.
  • 검색은 정적 색인이다. 검색 노출을 켠 카드만 색인 파일에 들어가고, 검색 페이지가 브라우저에서 그것을 거른다. 켜고 끄면 색인이 다시 만들어진다.

7. 자주 묻는 것

Q. 검색 노출을 껐는데 왜 아직 보이나요? 검색 노출은 "찾아지느냐"이지 "보이느냐"가 아니다. 안 보이게 하려면 지워야 한다(§4).

Q. AI에게 "카드 지워 줘"라고 했는데 못 한대요. 맞다. AI는 만들 수만 있고 지우거나 검색 노출을 바꾸지 못한다. 콘솔에서 한다. 공개된 것을 내리는 결정은 사람이 화면에서 확인하고 누르게 두었다.

Q. 이미지에서 요약이 잘렸어요. 요약 여러 줄이 이미지의 한 공간을 나눠 써서 그렇다. AI가 만들 때 어느 줄이 잘렸는지 알려 준다. 줄여서 다시 만들거나(§5), 페이지에는 전문이 있으니 그대로 둔다.

Q. 카드에 남의 이름이 들어갔어요. 지금 지우라. 지우면 페이지는 즉시 내려간다. 캐시는 한동안 남을 수 있으니 이미 공유했다면 그 사실을 알고 있어야 한다.

Q. 카드에서 내 기억으로 돌아갈 수 있나요? 없다. 카드는 원본과 끊긴 스냅샷이다. 받는 사람은 AiAkiv 회원도 아니고, 내 기억을 읽을 권한도 없다.

Q. 팀 기억으로 카드를 만들 수 있나요? 내가 읽을 수 있는 기억이면 된다. 다만 카드는 만든 사람 개인 소유이고 공개 범위는 전 세계다. 팀의 기억을 밖에 내놓는 일이니 팀 규칙에 맞는지 먼저 본다.


8. AI를 위한 안내

이 절은 AiAkiv에 연결된 AI가 읽는다. 사람이 "카드 만들어 줘"라고 했을 때 무엇을 어떤 순서로 하고, 무엇을 반드시 말해야 하는지다.

도구

카드는 전용 도구가 아니라 앱 공용 창구 하나로 만든다.

run_aiakiv_app_action(app="card", action="describe")            # 형식을 묻는다
run_aiakiv_app_action(app="card", action="create", data={...})  # 만든다
  • actiondescribecreate 둘뿐이다. 삭제·수정·검색 노출 변경은 이 도구로 할 수 없다: 사용자에게 콘솔(데이터 → 카드)을 안내한다.
  • 공개 닉네임과 분류 태그도 이 도구로 못 한다. 둘 다 사람이 콘솔에서 정하는 것이다(§4). "태그 붙여 줘", "내 이름 넣어 줘" 라는 요청에는 할 수 있다고 답하지 말고 콘솔 위치를 알려준다. data.tags 는 그것과 다른 것이다: 카드 이미지에 새겨지는 카드 자체 태그이고, 만들 때 한 번만 정해진다.
  • data는 JSON 객체 또는 JSON 문자열. 본문이 길고 여러 줄이면 인자가 뭉개질 수 있으니 그럴 때는 문자열로 보낸다.
  • 형식을 정확히 모르면 먼저 describe를 부른다. 추측하지 않는다.

절차

  1. 기억을 검색한다: search_memory로 주제를 모은다(검색하기). 기억에 없는 것을 지어내지 않는다. source_count에는 실제로 쓴 기억 수를 넣는다.
  2. 민감한 것을 거른다: 개인 이름·이메일·내부 주소·아직 공개되면 안 되는 결정. 카드는 만드는 순간 공개된다. 애매하면 사용자에게 초안을 먼저 보인다.
  3. 형식에 맞춰 쓴다: 아래 필드와 한도. 특히 요약은 이미지 안전선을 지킨다.
  4. create를 부른다.
  5. 응답의 notice를 사용자에게 가장 먼저 전한다. 그다음 주소, 그다음 요약. 줄이지 않는다.
  6. fit이 있으면 무엇이 잘렸는지 그대로 알린다. 다시 만들지 여부는 사용자가 정한다. 다시 만들면 새 카드가 생기고 이전 카드는 남는다는 것을 함께 말한다.

필드와 한도 (describe 응답과 같다)

필드 필수 한도
title 문자열 80자
bullets 문자열 배열 3~5개, 각 120자. 이미지 안전선은 훨씬 짧다(아래)
conclusion 문자열 200자
source_count 정수 0 이상. 실제로 쓴 기억 수
tags 문자열 배열 3개, 각 20자. 검색어가 된다
body 문자열 3만 자, 제한된 마크다운

제목·요약·결론·태그는 한 줄 필드다. 개행을 넣으면 공백으로 접힌다. 본문만 개행이 문법이다.

본문에서 되는 문법: 문단, ## 제목, - 목록, 1. 목록, > 인용, `코드`, ``` 블록, **굵게**, *기울임*, [글자](https://…), ---. 그 밖은 글자로 나온다. 링크는 http(s)만 링크가 된다. HTML을 넣어도 코드로 실리지 않는다.

요약 안전선: 한도만 지키면 잘린다

describebullets.renders가 실측값을 준다. 현재 값:

  • safe_chars_per_line: 30자 (한글 기준 최악값. 영문·공백은 더 들어간다)
  • max_lines_each: 3줄

요약 여러 개가 한 공간을 나눠 쓴다. 다섯 개를 각 90자로 쓰면 각 120자 한도는 지켰지만 이미지에서 전부 잘린다. 안전한 목표:

  • 요약 5개면 각 30자 안팎(1줄): 아니면
  • 요약 3개면 각 60~90자(2~3줄)

이 값은 재서 만든 것이니 손으로 외우지 말고 describe에서 읽는다. 목표는 한 번에 맞추는 것이다. 다시 만들기는 공짜가 아니다.

응답 읽기

성공:

{
  "notice": "TELL THE USER BEFORE ANYTHING ELSE: this card is already live … ",
  "ok": true, "app": "card", "key": "kx7mabcd23",
  "url": "https://card.aiakiv.com/kx7mabcd23",
  "og_url": "…/og.png", "square_url": "…/square.png",
  "title": "…", "tags": ["…"], "revision": 1,
  "fit": { "fits": false, "bullets_truncated": [3, 5], "hint": "…" }   // 잘렸을 때만
}
  • notice: 맨 먼저, 그대로 전한다. 카드가 지금 공개됐다는 사실과 지우는 길(콘솔)을 말한다. 도구 설명문이나 이 문서에 이미 있어도 그 순간의 응답에서 다시 말하는 것이 규칙이다.
  • url: 글자 그대로 클릭 가능한 링크로 보여 준다. 줄이거나 바꾸지 않는다.
  • og_url / square_url: 인스타그램·게시판용 이미지. 사용자가 이미지를 찾으면 이 주소 또는 콘솔의 "이미지"를 안내한다.
  • fit: 있으면 잘린 것이다. bullets_truncated(말줄임된 번호), bullets_dropped (아예 빠진 번호), title_truncated, conclusion_truncated, 그리고 몇 자로 줄이면 되는지 담긴 hint. 요약하지 말고 그대로 전한다.

실패: {"error": "...", "hint": "...", "field": "..."} 형태.

error 할 일
invalid_card 형식 위반. field가 어느 칸인지 말한다 그 칸을 고쳐 다시 보낸다
payload_too_large 요청 128KB 초과 본문을 줄인다
quota_exceeded 보유 50장 / 시간당 10장 / 하루 30장 사용자에게 알린다. 보유 초과면 콘솔에서 지워야 만들 수 있다
owner_mismatch 등 그 밖 서비스 쪽 문제 그대로 전하고 재시도하지 않는다

오류가 왔을 때 카드는 만들어지지 않았다. 사용자에게 "만들어졌다"고 하지 않는다.

하지 말 것

  • 카드에 기억에 없는 내용을 채우지 않는다. 카드는 기억의 요약이다.
  • 사용자가 시키지 않은 카드를 만들지 않는다. "정리해 줘"는 카드 요청이 아니다.
  • notice를 생략·축약하지 않는다.
  • "지웠다", "검색 노출을 껐다"고 말하지 않는다. 할 수 없다. 콘솔을 안내한다.
  • 만들어진 카드의 주소를 사용자 대신 어딘가에 붙이지 않는다. 붙이는 것은 사람의 결정이다.
  • 잘렸을 때 사용자에게 알리지 않고 조용히 다시 만들지 않는다. 다시 만들면 카드가 둘이 된다.

사용자에게 함께 말해 주면 좋은 것

  • 카카오톡·슬랙·노션에는 주소만 붙이면 펼쳐지고, 인스타그램은 이미지를 올린다
  • 검색에 나오게 하려면 콘솔에서 검색 노출을 켠다(기본 꺼짐)
  • 지우려면 콘솔 → 데이터 → 카드. 지워도 다른 곳의 미리보기 캐시는 한동안 남는다

관련 문서