Communitygithub.com

ascii

말로 설명하거나 이미지를 주면 움직이는 ASCII 아트를 Python 코드로 새로 만든다. 질문 → ① 정지 그림 → ② 등장 → ③ 모션 → 최종본 순서로, 단계마다 사용자가 마음에 들 때까지 고친다. "/ascii 파도치는 바다", "/ascii 우주 속의 눈", "/ascii 회전하는 3D 도넛", "/ascii 초원을 뛰는 말"처럼 쓰고, 이어서 할 때는 "/ascii <작품이름> <고칠 점>".

ascii란 무엇인가요?

ascii is a Claude Code agent skill that 말로 설명하거나 이미지를 주면 움직이는 ASCII 아트를 Python 코드로 새로 만든다. 질문 → ① 정지 그림 → ② 등장 → ③ 모션 → 최종본 순서로, 단계마다 사용자가 마음에 들 때까지 고친다. "/ascii 파도치는 바다", "/ascii 우주 속의 눈", "/ascii 회전하는 3D 도넛", "/ascii 초원을 뛰는 말"처럼 쓰고, 이어서 할 때는 "/ascii <작품이름> <고칠 점>".

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/applelog/ascii-art-studio/tree/HEAD/.claude/skills/ascii

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

/ascii — 움직이는 ASCII 아트를 Python 코드로

요청: $ARGUMENTS

결과물은 언제나 실행되는 Python 코드(pieces/<slug>/piece.py)다. 대화에서 보여 주는 PNG·MP4·프레임 띠는 그 코드를 실제로 실행해서 뽑은 미리보기일 뿐이다. 이미지 생성 AI나 별도 스크립트로 미리보기를 만들지 않는다. 사용자가 python piece.py를 돌리면 대화에서 본 것과 같은 결과가 나와야 한다.

작업 전에 reference.md(엔진 사용법·레시피·점검표)와 template.py(작품 뼈대)를 읽는다. 전체 계획은 docs/PLAN.md에 있다.

지킬 것 (모든 단계)

  • 사용자에게는 한국어로 답한다.
  • 명령은 source "$(conda info --base)/etc/profile.d/conda.sh" && conda activate min && 뒤에 실행한다. 사용자에게 안내할 때는 conda activate min 없이도 되는 전체 경로 /opt/homebrew/Caskroom/miniforge/base/envs/min/bin/python …을 쓴다.
  • 한 단계씩. 사용자가 분명히 승인해야("좋아", "다음", "마음에 들어") 다음 단계로 간다. 애매하면 승인인지 묻는다.
  • 수정은 지금 단계만. 이미 승인된 단계를 바꿔야 하는 요청이면 어느 단계로 돌아가는지 말하고 확인받는다. 돌아가면 그 뒤 단계는 다시 승인받는다.
  • 버전은 코드로 남긴다. 미리보기를 보여 줄 때마다 --version s1_v1처럼 저장해서 versions/<버전>/에 코드와 미리보기가 함께 남게 한다. "아까 v2가 나았어"라고 하면 versions/s1_v2/piece.py를 piece.py로 되돌리고 다시 렌더해서, 미리보기와 픽셀이 같은지 확인한다.
  • 미리보기를 보여 줄 때는 만든 명령과 버전을 같이 적는다.
  • 직접 보지 않은 것은 "확인함"이라고 하지 않는다. PNG와 프레임 띠는 Read로 직접 보고 판단한다. 움직임의 느낌(속도, 부드러움)은 사용자가 MP4나 창으로 판단해 달라고 한다.

0. 상황 파악

  • 요청이 기존 pieces/<slug> 이름이거나 "방금 그거"를 가리키면 이어서 하기다. brief.md의 "진행 상태"를 읽고 그 단계에서 계속한다. 고칠 점이 분명하면 묻지 않고 그 단계만 고친다.
  • 그 밖에는 새 작품이다.

1. 애매하면 먼저 묻는다 (새 작품)

요청이 짧아서 결과가 크게 갈리는 항목이 비어 있으면, 코드를 쓰기 전에 AskUserQuestion으로 묻는다.

질문 항목은 고정된 목록이 아니다. 요청한 대상과 장면을 보고 그 작품의 결과에 가장 큰 영향을 주는 항목을 그때그때 고른다. 아래는 예시일 뿐이고, 한 유형의 질문을 다른 작품에 그대로 쓰지 않는다. 특정 대상(예: 말)을 이 프로젝트의 대표 목표로 여기지 않는다.

요청 예대상 유형이런 것을 물을 수 있다
/ascii 초원을 뛰는 말이동하는 생물제자리인지 가로지르는지(어디서 어디로), 방향과 시점, 걸음걸이와 속도, 배경
/ascii 파도치는 바다자연 현상·풍경보는 시점(수평선 정면·위·해변), 파도 세기와 리듬, 시간대와 빛, 거품·물보라
/ascii 우주 속의 눈장면 전환·초현실막 구성(눈 → 줌 → 우주), 길이와 막별 시간, 분위기, 반복 여부
/ascii 회전하는 3D 도넛3D 물체·장면물체가 도는지 카메라가 도는지, 면·선·점 중 표현, 빛과 그림자, 재질, 회전 축과 속도
/ascii LOVE글자·타이포등장·변형 방식, 읽히는 시간, 크기와 배치
사진 첨부이미지 기반무엇을 움직일지, 원래 색을 쓸지 다시 칠할지, 피사체만 쓸지 배경도 쓸지

어느 작품에나 해당할 수 있는 공통 후보: 화면 비율(가로·정사각·세로), 그리는 방식(밝기 글자 채움·윤곽 기호·둘 다)과 글자 밀도, 색과 바탕 밝기, 루프 길이.

규칙:

  • 한 번에 최대 4개, 결과 차이가 큰 것부터 묻는다.
  • 질문마다 추천안을 첫 선택지로 두고 (추천)을 붙인다. 선택지 설명에는 그 선택으로 화면이 어떻게 보이는지 한 줄로 적는다.
  • 요청에 이미 있는 것은 다시 묻지 않는다.
  • "알아서", "맡길게"라고 하면 묻지 않고, 정한 값을 brief.md의 "기본값으로 정한 것"에 적는다.
  • 이미지만 왔고 움직임 설명이 없으면 움직임은 반드시 묻는다. 정지 이미지로 움직임을 정하지 않는다.
  • ① 단계에서는 그림에 관한 것만 묻는다. 등장 방식은 ②, 움직임 세부는 ③에서 묻는다. 단, 이동 경로처럼 구도에 영향을 주는 것은 ①에서 묻는다.

2. 참고 사진으로 디테일을 정한다

새로 만드는 모든 대상은 상상만으로 그리지 않고 실제 모습을 참고한다.

  1. 사용자가 사진이나 레퍼런스를 줬으면 그것을 먼저 쓴다.
  2. 없으면 사진을 검색해 실제 모습을 확인한다(WebSearch, 브라우저). 예: "small wooden fishing boat side view", "galloping horse side view".
    • 검색한 사진은 화면으로만 본다. 파일로 내려받아야 하면 파일 이름·출처·크기를 말하고 먼저 허락을 받는다.
  3. 뽑은 것을 brief.md의 "참고한 모습"에 적는다.
    • 전체 비율과 실루엣
    • 알아보게 하는 특징 부위 3~6개
    • 빛
    • 이 글자 해상도에서 보일 크기인지(너무 작은 디테일은 빼거나 과장)
    • 출처와, 본 것과 추정한 것의 구분
  4. 특징 부위는 맨 앞 설정 변수로 만든다(예: BOW_RISE, CABIN_W, MANE_LEN).
  5. 사진은 형태를 보는 참고로만 쓴다. 사진을 그대로 글자로 옮기는 것은 사용자가 원할 때만 이미지 입력(아래 3)으로 한다.

3. 작품 폴더 만들기

python tools/new_piece.py <slug> --title "<제목>" --request "<사용자 원문>"
  • slug는 영문 소문자와 하이픈으로 쓴다(예: ocean-waves).
  • pieces/<slug>/에 piece.py(템플릿), brief.md, GLOSSARY.md가 생긴다. 이미 있으면 덮어쓰지 않는다.
  • 사용자 이미지로 글자 그림을 만들 때는 필드를 뽑는다. --cols와 --cell-aspect는 작품 설정과 같게 한다. 원본 이미지는 작품 폴더에 넣지 않는다.
python tools/image_to_field.py <이미지> --out pieces/<slug>/field.json --cols <COLS> --ss 2 --cell-aspect <CELL_ASPECT>

4. 작품 코드 쓰는 법 (모든 단계 공통)

  • 맨 앞 설정 블록(C의 #define처럼).
    • 바꿀 만한 값은 전부 맨 앞에 두고, 아래 코드에는 숫자를 직접 쓰지 않는다. 0, 1, 2, 0.5만 예외다. 색은 rgb01(SOME_RGB)처럼 엔진 함수로 바꾼다.
    • 변수마다 한 줄 주석을 단다. 형식은 # 뜻 (단위·범위)이고, 끝 괄호가 용어집의 범위 칸이 된다.
    • 설정 블록은 # ===== ① 장면 설정 =====, ② 등장 설정, ③ 모션 설정, 최종 출력, 효과 소제목으로 나눈다. 작품 고유 숫자 변수의 범위는 RANGES에 둔다.
  • 그림 함수 하나(draw(s, phase, grid))로 단계를 잇는다. 이렇게 하면 단계 연결 검사가 저절로 맞는다.
    • scene = draw(0)
    • motion = draw(phase): 모든 시간 변화는 phase의 정수 주기. loop_sin, round(SPIN) 등을 쓴다.
    • intro(p): 완성 화면을 가렸다가 드러낸다. p=1이면 완성 화면 그대로.
  • 결정성: 렌더 경로에서 random과 time을 쓰지 않는다. 난수는 setup()에서 SEED로만 만든다. 무작위 사건은 schedule.make_schedule로 일정표를 미리 만든다.
  • 무거운 계산은 setup에서 미리 해 둔다(좌표, 마스크, 순서). 한 프레임이 길어지면 엔진이 작업자 프로세스로 미리 계산하지만, 60ms를 넘지 않게 한다.
  • 엔진 함수를 쓴다. 엔진에 없는 기능을 작품 안에 임시로 짰다면, 엔진에 같은 기능이 생긴 뒤 엔진 것으로 바꾼다. 바꾼 뒤 그림이 같은지 픽셀로 확인한다.
  • 한글 글자는 Menlo에 없다. 글자로 쓸 문구는 영어나 기호로 하거나, 한글 글꼴 경로를 FONT에 넣는다.

5. ① 정지 그림

  1. draw()와 setup()을 요청에 맞게 쓴다. 템플릿의 빛나는 공은 지운다.
  2. 검증한다.
    python -m pytest -q tests/test_pieces.py -k <slug>
    python pieces/<slug>/piece.py --check
    
  3. 렌더하고 버전을 남긴다.
    python pieces/<slug>/piece.py --stage 1 --version s1_v1
    
    versions/s1_v1/preview.png를 Read로 직접 본다. 형태가 읽히지 않거나 너무 빽빽하거나 비면 고쳐서 다시 렌더한 뒤 보여 준다. 보여 주기 전에 고친 시도는 버전으로 남기지 않아도 된다.
  4. 보여 준다.
    • SendUserFile로 PNG를 보내고, 명령과 버전을 적는다.
    • 무엇을 어떻게 그렸는지 3~5줄로 설명한다.
    • 아쉬운 점을 솔직히 적는다.
    • 바꿔 볼 만한 설정 변수 2~4개를 "이 값을 바꾸면 이렇게 된다" 형식으로 제안한다.
  5. brief.md의 "진행 상태"와 "수정 기록"을 고치고, 용어집을 갱신한다.
    python tools/glossary.py pieces/<slug>/piece.py
    
  6. 승인 여부를 묻는다(wrap_up 버튼: "고칠 게 있어" / "① 승인"). 고칠 점이 오면 그 부분만 고치고 s1_v2로 다시 보여 준다. 횟수 제한은 없다.

6. ② 등장 방식

  1. 등장 방식을 고른다. 사용자가 정하지 않았으면 이 작품에 어울리는 후보 2~4개를 추천안과 함께 묻는다. 아래는 예시이고 고정 목록이 아니다.
    • 타자기: 왼쪽 위부터 한 글자씩
    • 스캔: 위→아래로 쓸어내림
    • 해독: 무작위 글자가 섞이다 제자리 글자로
    • 밝기 순: 어두운 글자부터
    • 모여들기: 흩어진 글자가 날아와 자리를 찾음
    • 장면 순서: 하늘 → 달 → 바다 → 배
    • 윤곽 먼저: 윤곽선을 그린 뒤 안쪽 채우기
    • 깊이 순(3D): 카메라 쪽부터
    • 페이드
  2. intro(s, p, grid)를 쓴다. 등장 순서 같은 고정 값은 setup()에서 만들고, p=1이면 scene과 같게 한다.
  3. 검증하고 렌더한다.
    python pieces/<slug>/piece.py --check
    python pieces/<slug>/piece.py --stage 2 --version s2_v1
    
    strip.png를 직접 보고 등장 순서가 의도대로인지 확인한다. 버전 폴더에는 strip.json(띠를 만든 단계·프레임)이 함께 남고, 테스트가 그 버전 코드로 같은 띠를 다시 만들어 픽셀까지 비교한다.
  4. MP4와 프레임 띠를 보여 주고, 속도·느낌은 사용자가 MP4로 판단해 달라고 한다. 승인되면 ③으로 간다.

7. ③ 모션

  1. 무엇이 어떻게 움직이는지 정하지 않았으면 묻는다(무엇이, 속도, 세기, 루프 길이).
  2. motion은 draw(phase)로 쓴다. 모든 주기는 정수로 맞춘다.
  3. 검증하고 렌더한다.
    python pieces/<slug>/piece.py --check
    python pieces/<slug>/piece.py --stage 3 --version s3_v1
    
    루프 이음매가 튀지 않는지 --check로 확인하고, 프레임 띠로 변화가 보이는지 본다.
  4. 창 재생 속도를 잰다. 무거우면 미리 계산할 것을 setup()으로 옮기거나 해상도·SUPERSAMPLE·MAX_STEPS를 줄인다.
  5. MP4와 프레임 띠를 보여 주고 승인을 받는다.

8. 최종본

python pieces/<slug>/piece.py --final --version final
python tools/glossary.py pieces/<slug>/piece.py
python -m pytest -q tests/test_pieces.py -k <slug>

보고에 넣을 것:

  • 실행 방법(python pieces/<slug>/piece.py, 키: Space·R·S·←→·Esc)
  • final.mp4, still.png
  • 바꿔 볼 만한 설정 변수
  • 테스트 결과와 확인하지 못한 것

brief.md의 진행 상태를 "완료"로 바꾼다.

9. 도움 파일

  • reference.md: 엔진 모듈별 함수, 레시피(필드 렌더·윤곽·등장·모션·노이즈·사건·잔상·이미지·3D), 품질 점검표, 자주 하는 실수
  • template.py: 단계 구조 작품 뼈대 (tools/new_piece.py가 복사함)
  • docs/PLAN.md: 전체 계획 (v4, v4+)

관련 스킬