일편나루 노트

AI와 실서비스를 개발할 때 지킨 규칙 — 비밀값 가리기 · 검증 후 적용 · 한 번에 묶기

※ 이 글은 제가 일본어로 쓴 글(jacepark.com)을 한국어로 옮긴 것입니다.한국어 학습 앱 「推し韓マル(오시한마루)」와 Web 「iffthen hangul」의 코드는 대부분 AI(Claude)와 함께 만들었습니다. 이 연재에서 지금까지 쓴 판정 엔진과 배포 구조도 그렇게 만든 것입니다. 진행 방식은 다음과 같습니다.AI는 저장소에 직접 접근하지 않는다. 조사·수정 명령을 AI가 쓰고, 사람이 자기 Mac에서 실행하고, 결과를 AI에게 돌려준다그래서 「AI가 무엇을 보는가」와 「무엇을 실행하게 하는가」를 규칙으로 통제해야 했다1. 조사 출력은 반드시 마스킹 필터를 거친다계기는 실제 사고였습니다. 다른 프로젝트에서 조사 명령의 출력(로그)에 외부 API 키가 그대로 찍혀 대화에 올라간 적이 있습니다..

한글을 「발음대로」 가타카나로 바꾸는 변환기를 만들었다 — 글자대로 바꾸면 읽기가 틀리는 이유

※ 이 글은 제가 일본어로 쓴 글(jacepark.com)을 한국어로 옮긴 것입니다.글자대로가 아니라 소리대로일본어를 쓰는 학습자에게 한국어 읽기를 가타카나로 보여 줄 때, 글자를 하나씩 바꾸면 틀린 발음이 됩니다.한국어글자대로(틀림)실제 발음(이 변환기)감사합니다カムサハプニダカムサハムニダ(비음화)맛있어요マッイッオヨマシッソヨ(연음)같이カッイカチ(구개음화)좋아요チョッアヨチョアヨ(ㅎ 탈락)국물クッムルクンムル(비음화)신라シンラシルラ(유음화)밥 먹었어?パプ モゴッソ？パム モゴッソ？(띄어쓰기를 넘는 비음화)(오른쪽 열은 이 글의 변환기를 실제로 돌린 결과입니다.)한국어 학습 앱 「推し韓マル(오시한마루)」의 읽기 표기와, Web 「iffthen hangul」의 읽기 화면에서 쓰는 변환 구조입니다.구조: 규칙을 먼저..

앱 콘텐츠를 업데이트 없이 전달하는 배포 파이프라인 — 원천 파일 → DB → 암호화 → 부분 글꼴 → 서버 → 앱

※ 이 글은 제가 일본어로 쓴 글(jacepark.com)을 한국어로 옮긴 것입니다.한국어 학습 앱 「推し韓マル(오시한마루)」에서는 기본 단어 5,500여 개·예문·리얼 회화·유행어·「今日の韓国語(오늘의 한국어)」를 매달 앱 업데이트 없이 전달하고 있습니다. 그 배포 흐름을 정리합니다.전체 흐름content-src/**/*.jsonl (사람이 고치는 원천 · git) │ build_content.py 검증 → SQLite (같은 원천 = 같은 결과 · content_version = 해시) │ check_examples.py 예문 정합 점검 (보고) │ build_fonts.mjs 쓰는 글자만 남긴 부분 글꼴 │ pack_assets.mjs 앱 내장본 암호화 ▼..

일본 재류카드와 마이넘버카드를 한 장으로 — 비자 갱신 때 신청하면 무료, 대신 온라인 신청은 안 됩니다

일본에 사는 외국인은 지금까지 재류카드와 마이넘버카드를 따로 들고 다녀야 했습니다. 2026년 6월부터 이 두 장을 한 장으로 합친 「특정재류카드(特定在留カード)」를 받을 수 있게 되었습니다.편해 보이지만, 받는 방법에 따라 비용과 시간이 꽤 달라집니다. 특히 비자 갱신을 온라인으로 하면 받을 수 없다는 점은 미리 알아 두는 편이 좋습니다. 출입국재류관리청의 공식 안내와 Q&A를 읽고 정리했습니다.찾아본 것공식 안내에 적혀 있던 것꼭 바꿔야 하나선택 사항입니다. 지금처럼 두 장을 따로 가져도 됩니다비용6월 14일 이후 처음 하는 갱신 등과 함께 받으면 원칙적으로 무료가장 큰 조건당분간 온라인 신청으로는 받을 수 없고, 입관 창구에서 신청해야 합니다이 글은 2026년 10월 30일에 출입국재류관리청 「特定..

프레임워크 없이 정적 사이트 9,400페이지를 만들고 SEO를 자동화했다 — lastmod·IndexNow·hreflang 다루기

※ 이 글은 제가 일본어로 쓴 글(jacepark.com)을 한국어로 옮긴 것입니다.Web 「iffthen hangul」은 일본어·한국어·영어·스페인어 4개 언어로, 페이지가 9,432장입니다. 이 사이트를 프레임워크 없이 만들고 SEO 작업을 자동으로 돌린 방법을 정리합니다.왜 프레임워크 없이인가페이지 구성은 단순합니다. 언어마다 톱·쓰기 화면·글자 목록·글자 페이지 2,351장·약관 3종입니다. 움직이는 부분(판정·읽기 변환)은 작은 스크립트 몇 개뿐입니다.그래서 Node 스크립트 하나(build.mjs)가 HTML 문자열을 만들어 파일로 쓰는 방식을 골랐습니다. 의존하는 것은 부분 글꼴 생성용 하나뿐입니다. 빌드 결과는 공유 호스팅에 rsync로 올립니다.[hangul-build] 배포 빌드 → d..

Cloudflare Workers 무료 플랜으로 판정 API를 운영한다 — 정답 데이터를 브라우저에 넘기지 않기 위한 설계

※ 이 글은 제가 일본어로 쓴 글(jacepark.com)을 한국어로 옮긴 것입니다.왜 서버에서 판정하나판정 코드는 순수 함수라 브라우저에서도 돌릴 수 있습니다. 다만 그러려면 2,351자 분량의 정답 획 좌표를 브라우저에 보내야 합니다. 좌표 데이터는 사람이 하나하나 검수한 자산입니다. 통째로 수집되면 곤란합니다.그래서 Web에서는 다음처럼 나눴습니다.정답 좌표는 서버 안에만 둔다브라우저는 「지금 쓴 획」만 보내고, 서버는 「맞음 / 틀림 + 이유」만 돌려준다획순 재생은 미리 만든 영상으로 보여 준다획순 영상을 만든 방법은 지난 편에 정리했습니다.획 데이터 하나로 앱·Web·획순 영상·판정 서버를 맞춘다 — 2,351자 획순 데이터를 만든 방법서버는 Cloudflare Workers 무료 플랜입니다(하..

※ 이 글은 제가 일본어로 쓴 글(jacepark.com)을 한국어로 옮긴 것입니다.한글 쓰기 연습 서비스에서는 「획 데이터」를 네 곳에서 씁니다.쓰는 곳쓰는 방식앱(推し韓マル)획순 재생 · 한 획씩 판정Web 판정 서버(Cloudflare Workers)한 획씩 판정(정답 좌표는 서버 밖으로 내보내지 않음)Web 획순 영상글자마다 mp4로 미리 그려 둔다Web 글자 페이지 2,351장획 수 · 구성 표시원천은 stroke-approved.json이라는 파일 하나입니다. 어느 한 곳만 바뀌고 나머지가 그대로면 「재생은 이 순서인데 판정은 다른 순서」 같은 사고가 납니다. 그래서 원천을 하나로 정하고, 나머지는 전부 빌드로 만드는 것으로 했습니다. 한 획씩 판정하는 구조 자체는 지난 편에 정리했습니다.손글..

※ 이 글은 제가 일본어로 쓴 글(jacepark.com)을 한국어로 옮긴 것입니다.견본 글자 위에 손가락이나 마우스로 한글을 쓰면, 손을 뗄 때마다 그 한 획이 맞았는지 바로 알려 주는 기능을 만들었습니다. 한글 쓰기 연습 앱 「推し韓マル(오시한마루)」와 Web 「iffthen hangul」의 획순 판정입니다.틀렸을 때는 이유를 네 가지로 나눠 보여 줍니다.순서가 틀림(다른 획을 먼저 씀)자리가 틀림모양이 틀림(곧은 획을 꺾어 씀 등)방향이 틀림(거꾸로 그음)같은 획을 세 번 틀리면 그 획의 획순 영상을 다시 보여 줍니다. 대상은 자주 쓰는 한글 2,351자 전부입니다. Web에서 바로 써 볼 수 있습니다.첫 방식: 다 쓴 뒤 한꺼번에 판정했다(실패)처음에는 글자를 다 쓴 뒤 한 번에 보는 방식이었습니..

일본에서 일하는 한국인이라면 몇 년에 한 번은 재류기간 갱신(비자 갱신)을 합니다. 그동안 수수료는 오래 6,000엔으로 고정되어 있었는데, 2026년 10월 1일부터 크게 올랐습니다. 얼마가 됐는지, 언제 신청한 것부터 해당하는지 출입국재류관리청의 공식 발표를 찾아 읽어 봤습니다.찾아본 것공식 발표에 적혀 있던 것갱신·변경 수수료일률 6,000엔 → 허가되는 재류기간에 따라 1만 엔~7만 5천 엔(창구)영주 허가1만 엔 → 20만 엔언제 신청분부터2026년 10월 1일 이후 신청분부터. 9월 30일까지 접수된 신청은 이전 금액이 글은 2026년 10월 28일에 출입국재류관리청의 공지 페이지와 공식 리플릿(2026년 9월 발행)을 읽고 정리한 것입니다. 글쓴이가 행정사는 아니며, 개인의 수수료를 확정해 ..

일본에서 회사에 다니다 보면 연말이 가까워질수록 동료들 사이에서 「후루사토 납세(ふるさと納税)」라는 말이 자주 나옵니다. 지방자치단체에 기부하면 세금이 줄고 답례품도 받는다는 제도인데, 외국인도 할 수 있는지, 언제까지 해야 하는지 헷갈리기 쉽습니다. 그래서 총무성 자료와 자치단체의 공식 안내를 찾아 읽어 봤습니다.찾아본 것공식 자료에 적혀 있던 것외국인도 되나제도는 소득세·주민세에서 공제하는 구조이고, 국적 조건은 적혀 있지 않았습니다올해 분 기한공제는 기부한 해를 기준으로 하므로, 올해 분은 12월 31일까지 기부해야 합니다가장 큰 주의점이듬해 1월 1일에 일본에 주소가 없으면 주민세 쪽 공제를 받을 수 없습니다이 글은 2026년 10월 28일에 총무성 자료(자치단체 게재본)와 에도가와구·이타바시구·..