The easiest way to make your first post is to edit this one. Go into /_posts/ and update the Hello World markdown file. For more instructions head over to the Kiko Now repository on GitHub.
]]>요즘은 초안을 LLM이 곧잘 씁니다. 그런데 LLM에게 “가이드 문서 하나 써줘”라고 하면, 그럴듯하지만 타입이 애매하고 구조가 매번 다른 글이 나옵니다. LLM은 글은 잘 쓰지만 검증된 문서 구조·팀 고유 서식·결정적(deterministic) 판정 같은 건 잘 못합니다. 그 간극을 메우려고 MCP 서버를 하나 만들어 깃허브에 올렸습니다. 이름은 Technical Writing Helper(twh)입니다.
포지셔닝을 한 문장으로 정리하면 이렇습니다. “글은 Claude가 쓰고, 구조·재료·출처 추적은 서버가 한다.” 이 역할 분담이 이 프로젝트의 거의 모든 설계 결정을 지배했습니다.
“좋은 목차 잡아주는 프롬프트” 하나면 되지 않나 싶을 수 있습니다. 실제로 해보면 세 가지가 안 됩니다.
MCP(Model Context Protocol)는 이 셋을 정면으로 해결합니다. 규칙은 서버 코드에 결정적으로 박아두고, 상태는 서버가 파일로 들고 있고, 같은 코어를 여러 입구로 서빙할 수 있습니다. 그래서 프롬프트가 아니라 서버로 갔습니다.
가장 먼저 정한 뼈대는 코어 라이브러리 + 얇은 프론트엔드입니다. 판정·목차·검색 로직은 전부 outline / references / doc_types / storage 모듈에 있고, MCP 서버(server.py)와 CLI(cli.py)는 그걸 얇게 노출하는 껍데기입니다.
┌─────────────┐
Claude (MCP) ─────▶│ server.py │─┐
└─────────────┘ │
┌─────────────┐ │ ┌──────────── core ───────────┐
CI / docs-as-code ▶│ cli.py │─┼──▶│ outline · references · │
└─────────────┘ │ │ doc_types · storage · extract│
┌─────────────┐ │ └──────────────────────────────┘
DocPortal 위키 ─▶│ import twh │─┘
└─────────────┘
덕분에 같은 규칙이 세 입구에서 똑같이 돕니다. 개인은 Claude Desktop/Code의 MCP로, CI는 CLI로, 전사 문서 포털(DocPortal)은 코어를 직접 import해서 위키 에디터의 “구조 잡기” 패널로. 나중에 원격 HTTP 서버로 전환할 때도 코어는 그대로 두고 껍데기만 바꾸면 됩니다.
server.py가 얼마나 얇은지는 툴 정의만 봐도 보입니다. 로직이 없습니다.
@mcp.tool()
def suggest_outline(doc_type: str, topic: str, audience: str, reader_goal: str) -> dict:
types = _types()
if doc_type not in types:
return {"ok": False, "error": f"알 수 없는 문서 타입: {doc_type}",
"available": sorted(types.keys())}
return outline_mod.suggest(types[doc_type], topic=topic,
audience=audience, reader_goal=reader_goal)
이 프로젝트에서 가장 마음에 드는 결정입니다. LLM에게 “먼저 독자를 물어보고 쓰세요”라고 지시문으로 부탁하면, 급할 때 건너뜁니다. MCP 서버는 대화를 주도할 수 없으니, 인터뷰를 파라미터로 강제했습니다.
classify_document는 reader_purpose와 audience를 필수로 받습니다. 그리고 reader_purpose가 정해진 enum이 아니면, 판정 대신 되물을 질문 목록을 돌려줍니다.
def classify(doc_types, reader_purpose, audience, topic=""):
if reader_purpose not in VALID_PURPOSES:
return {
"ok": False,
"error": "reader_purpose가 유효하지 않습니다. 독자에게 "
"'이 문서를 읽고 나서 무엇을 할 수 있어야 하나요?'를 물어본 뒤 고르세요.",
"valid_purposes": [...], # learn-by-doing | accomplish-task | ...
}
primary = [t for t in doc_types.values() if reader_purpose in t.reader_purposes]
...
즉 인터뷰를 건너뛰고 바로 classify_document를 부르면 서버가 “그건 유효한 값이 아니니 사용자에게 물어보라”고 되받아칩니다. LLM 입장에서는 인터뷰 없이는 다음 단계로 갈 방법이 없습니다. 하지 말라고 부탁하는 대신, 안 하면 진행이 안 되게 만든 것입니다.
문서 타입 판정은 LLM의 감이 아니라 서버의 규칙으로 합니다. 기준 축은 딱 하나 — “독자가 읽고 나서 무엇을 할 수 있어야 하는가”(reader_purpose)입니다. learn-by-doing이면 tutorial, accomplish-task면 how-to, report-official이면 공문·보고서 식으로, 목적 → 타입 매핑을 서버가 들고 있습니다. 같은 입력엔 항상 같은 판정이 나옵니다.
내장 타입은 Diátaxis 4종(tutorial / how-to / reference / explanation)에 README, 릴리스 노트, ADR, 트러블슈팅, API 레퍼런스, 그리고 한국 실무에 꼭 필요한 공문·보고서(관공서/대내)까지 얹었습니다. 각 타입은 YAML 한 장으로 정의되는데, 사실상 이 스키마가 이 프로젝트의 핵심 자산입니다. 섹션마다 제목뿐 아니라 “이 섹션이 답해야 할 질문”과 분량 가이드가 붙습니다.
- title: 소요 예산 및 일정
goal: 자원과 시간 계획을 명시한다.
questions:
- 예산의 산출 근거는 무엇인가?
- 단계별 일정과 책임 주체는 명확한가?
length_hint: 표 권장
optional: true
suggest_outline은 이 섹션들을 그대로 목차로 돌려주고, 각 질문이 곧 라이터에게 던지는 체크리스트가 됩니다. 팀 고유 타입은 save_team_template로 같은 스키마로 추가하면 내장 타입과 똑같이 동작합니다(같은 id면 팀 템플릿이 우선). 내장 타입은 패키지 안에, 팀 템플릿은 프로젝트의 .twmcp/에 — 코드와 데이터를 갈라놓은 것도 의도입니다.
참조 문서 기반 초안이 두 번째 축입니다. 여기서 서버의 몫은 명확합니다 — 수집·검색·출처 추적. 글은 여전히 Claude가 씁니다.
검색은 임베딩 대신 BM25를 자체 구현했습니다. MVP에서 무거운 의존성 없이 실용적인 정확도를 내는 게 목표였거든요. 문제는 한국어입니다. 공백 단위로 토큰을 자르면 조사가 붙은 “예산의”와 “예산을”이 서로 다른 토큰이 되어 매칭이 무너집니다. 형태소 분석기(KoNLPy 등)를 쓰면 정확하지만, 무거운 설치 의존성이 따라옵니다.
타협점은 문자 바이그램이었습니다. 영문은 단어 토큰으로, 한글은 2글자씩 슬라이딩하며 토큰으로 만듭니다.
_WORD_RE = re.compile(r"[a-z0-9_]+")
_HANGUL_RE = re.compile(r"[가-힣]+")
def tokenize(text: str) -> list[str]:
text = text.lower()
tokens = _WORD_RE.findall(text)
for run in _HANGUL_RE.findall(text):
if len(run) == 1:
tokens.append(run)
else:
# "예산안" → "예산", "산안"
tokens.extend(run[i:i+2] for i in range(len(run) - 1))
return tokens
“예산안”은 예산·산안으로 쪼개지므로 “예산”이 들어간 질의와 겹칩니다. 형태소 분석기만큼 정교하진 않지만, 조사 변화에 상당히 강인하고 의존성이 0입니다. 그 위에 정석 BM25 랭킹을 얹었습니다.
idf = math.log(1 + (n - df + 0.5) / (df + 0.5))
denom = tf + k1 * (1 - b + b * len(doc) / avg_len) # k1=1.5, b=0.75
scores[i] += idf * tf * (k1 + 1) / denom
중요한 건 인터페이스입니다. 검색은 ReferenceLibrary.search() 뒤에 숨어 있어서, 나중에 임베딩 검색으로 갈아끼워도 호출부는 안 바뀝니다. draft_section이 반환하는 근거 발췌의 단위는 ref_id#chunk_index인데, 이게 그대로 출처 표기 단위가 됩니다. 초안 문단 끝에 [ref: 작년보고서#3]처럼 남기라고 지침을 함께 돌려줘서, LLM이 근거 없이 지어내는 걸 구조적으로 억제합니다.
한국 공공·기업 문서의 현실은 한글 파일입니다. 작년 보고서(.hwpx)를 참조로 등록하고 올해 초안을 뽑는 흐름이 자연스럽게 성립하려면 hwpx를 읽어야 합니다. 그런데 여기서 발견이 하나 있었습니다 — hwpx는 개방 포맷(OWPML, KS X 6101)이라 그냥 ZIP + XML입니다. 한컴오피스도, 외부 라이브러리도 필요 없습니다.
def _extract_hwpx(path: Path) -> str:
paragraphs = []
with zipfile.ZipFile(path) as zf:
section_names = sorted(
n for n in zf.namelist()
if re.fullmatch(r"Contents/section\d+\.xml", n)
)
for name in section_names:
root = ElementTree.fromstring(zf.read(name))
# 네임스페이스 URI가 버전마다 달라서 로컬 이름(<hp:p>, <hp:t>)으로 매칭
for para in root.iter():
if para.tag.rsplit("}", 1)[-1] != "p":
continue
runs = [t.text or "" for t in para.iter()
if t.tag.rsplit("}", 1)[-1] == "t"]
text = "".join(runs).strip()
if text:
paragraphs.append(text)
return "\n\n".join(paragraphs)
한 가지 함정은 네임스페이스였습니다. hwpx 버전에 따라 XML 네임스페이스 URI가 달라져서 {네임스페이스}p로 정확히 매칭하면 어떤 파일은 잡히고 어떤 파일은 안 잡힙니다. 그래서 태그의 로컬 이름(} 뒤 부분)만 보고 p·t를 찾도록 했습니다. 버전이 뭐든 문단(p)과 텍스트 런(t)만 긁어오면 되니까요.
.md/.txt/.rst와 .hwpx는 이렇게 표준 라이브러리만으로 처리하고, PDF·DOCX·구형 .hwp만 선택 의존성(pip install 'twh[docs]')으로 뺐습니다. 설치 마찰을 최소화하는 방향입니다. 참고로 쓰기는 하지 않습니다 — 바이너리 .hwp 생성은 오픈소스로 불안정하고, 관공서 서식은 백지 생성보다 “기존 서식의 빈칸 채우기”가 실무와 맞기 때문입니다. 안 되는 걸 되는 척하지 않는 게 도구의 신뢰성이라고 생각합니다.
.twmcp/ 파일로 두는가MCP 서버는 재시작되면 메모리가 날아갑니다. 그래서 세션을 넘겨 유지할 상태 — 참조 인덱스, 추출된 본문, 팀 템플릿 — 는 전부 프로젝트 루트의 .twmcp/에 파일로 저장합니다. 루트는 TWH_PROJECT_ROOT 환경변수로 지정합니다.
.twmcp/
references/
index.json # 참조 메타데이터
<id>.txt # 추출된 본문
templates/*.yaml # 팀 문서 타입
.twmcp/에는 회사·개인 데이터가 들어가므로 .gitignore로 커밋을 막습니다. 레포에는 범용 코드만, 서식·용어집·참조 인덱스 같은 조직 데이터는 프로젝트 상태로. 전사 사용 시 회사 자료가 개인 레포로 새어 들어가는 사고를 구조적으로 막는 장치입니다. 참조 id를 만들 때도 한글은 유지하되 파일명으로 안전하게 슬러그화하고, 같은 이름이 있으면 -2를 붙여 충돌을 피합니다.
이 구조의 값어치는 통합에서 드러났습니다. DocPortal 위키 에디터의 “구조 잡기” 패널은 MCP를 거치지 않고 코어를 직접 import합니다(GET /wiki/outline → twh.outline). 문서 타입·주제·독자·목표를 입력하면 작성 가이드 주석이 달린 목차 뼈대가 본문에 채워집니다. CLI로는 CI에서 이렇게 씁니다.
twh outline how-to --topic "SSO 연동" \
--audience "사내 개발자" --goal "SSO 로그인 붙이기" # 목차 스켈레톤
twh ref add ./작년보고서.hwpx --title "작년 보고서" # 참조 등록
twh ref search "예산 산출 근거" # BM25 검색
같은 판정·같은 목차·같은 검색이 Claude에서도, 포털에서도, CI에서도 동일하게 나옵니다. 코어를 한 번 잘 만들어두니 입구는 얼마든지 늘릴 수 있었습니다.
돌아보면 이 프로젝트에서 코드보다 오래 붙든 건 두 가지였습니다. 하나는 “글은 LLM, 구조와 근거는 서버”라는 역할 분담을 어디서도 흐리지 않는 것. 다른 하나는 템플릿 스키마 — 섹션마다 무엇을 물어야 하는가를 설계하는 일이었습니다. 후자는 사실 20년 된 테크니컬 라이팅 원칙을 YAML로 옮겨 적는 작업에 가까웠습니다.
라이터의 무게중심은 초안을 쓰는 데서, 무엇이 참인지 판별하고 그 판별 기준을 도구로 굳혀두는 쪽으로 옮겨가고 있습니다. 이 MCP 서버는 그 이동을 제 손으로 코드에 새겨본 결과물입니다. 빈 화면 앞의 막막함은 사라지지 않지만, 이제 그 막막함을 잘 설계된 질문 몇 개로 바꿔둘 수는 있게 됐습니다.
로드맵은 아직 남았습니다 — Fumadocs MDX 스캐폴딩, Pandoc 한글화 레이어, HWPX 서식 채우기, 목차 대비 섹션 검토. 하지만 Phase 1(인터뷰 → 판정 → 질문 달린 목차)만으로도 매일 쓰고 있습니다. 도구는 완성돼서 쓰는 게 아니라, 쓰면서 완성되는 것 같습니다.
]]>그런데 만드는 내내 묘한 감각이 따라다녔습니다. 그동안 제가 써온 문서를 이제 사람이 아니라 이 챗봇이 먼저 읽는다는 것. 사용자는 문서 페이지에 도착하지 않습니다. 챗봇에게 묻고, 챗봇이 저 대신 문서를 읽어 소화한 뒤, 조립된 답을 받아 갑니다. 문서는 여전히 소비되는데, 그 1차 독자가 사람에서 기계로 조용히 바뀌어 있었습니다.
가장 먼저 실감한 건 역설이었습니다. 챗봇이 잘 동작할수록 문서 사이트로 들어오는 사람은 줄어듭니다. 지표만 보면 문서의 존재감이 옅어지는 것처럼 보입니다. 하지만 실제로는 정반대였습니다.
챗봇이 엉뚱한 답을 하는 경우를 뜯어보면, 거의 예외 없이 원천 문서나 데이터에 문제가 있었습니다. 몇 가지는 지금도 기억에 남습니다. 챗봇이 내부 직원용 매뉴얼을 참조하는 바람에, 외부 사용자에게는 적용되지 않는 내부 프로세스를 그대로 안내한 적이 있었습니다. 어딘가에 명시해두지 않은 아주 간단한 할인율 같은 값은, 근거가 없으니 그럴듯하게 지어내 틀린 숫자를 답했습니다. 개발 과정에서 이미 바뀐 내용이 챗봇이 참조하던 레포에는 옛날 상태로 남아 있어서, 지금은 존재하지 않는 경로를 안내한 경우도 있었습니다.
예전 같으면 이런 문서는 사람을 잠깐 헤매게 하는 정도였습니다. 사람은 이상하다 싶으면 다른 페이지를 열어 스스로 보정하니까요. AI는 그렇게 하지 않습니다. 부정확한 문서를 확신에 찬 문장으로 증폭시킵니다. 틀린 근거 위에 매끄러운 답변을 얹어 사용자에게 건넵니다. 문서의 오류가 처음으로 ‘조용한 불편’이 아니라 ‘증폭되는 사고’가 되는 순간을, 저는 이 챗봇을 통해 처음 목격했습니다. 트래픽은 줄었지만 문서 한 줄의 무게는 오히려 무거워졌습니다.
그래서 문서를 손보기 시작했습니다. 청크 단위로 잘려도 스스로 완결되게, 제목 계층을 명시적으로, 암묵지를 걷어내고 다 적어놓는 쪽으로. 흥미로운 건 이 작업이 전혀 새롭지 않았다는 점입니다.
스캔 가능하게 써라, 모호함을 없애라, 구조적으로 배치하라. 20년 동안 테크니컬 라이팅이 반복해온 원칙 그대로였습니다. 달라진 건 기준의 강도가 아니라, 그 기준을 어겼을 때 벌어지는 일이었습니다. 예전에는 못 쓴 문서가 사람만 불편하게 했다면, 이제는 검색 품질 저하로, 챗봇 오답률로, 눈에 보이는 숫자로 되돌아옵니다. 잘 쓴 문서와 못 쓴 문서의 격차가 처음으로 측정 가능해진 것입니다.
돌이켜보면 토픽 기반 저술이 오래 주장해온 방향 — 완결된 부품으로서의 문단 — 을 AI가 강제로 현실화시켰을 뿐입니다. 사용자는 이제 튜토리얼을 처음부터 끝까지 읽지 않습니다. 자기 상황에 맞는 답을 조립받습니다. 그렇다면 제 일은 완결된 내러티브를 짓는 것에서, 어떤 질문에도 정확히 조립될 수 있는 신뢰할 수 있는 조각을 만드는 쪽으로 옮겨갑니다.
문서 바깥에서도 비슷한 걸 배웠습니다. 챗봇은 같은 인사말도 상황에 따라 다르게 받아들였고, 사람 이름 하나조차 국문과 영문, 대문자와 소문자를 저마다 다른 값으로 취급했습니다. 사람에게는 당연히 같은 것으로 읽히는 표기들이, 챗봇에게는 명시적으로 “이건 전부 같은 값입니다”라고 지도해주기 전까지는 서로 다른 것이었습니다.
문서를 쓸 때 제가 은연중에 독자의 상식에 기대어 생략해온 것들이, 여기서는 하나도 통하지 않았습니다. 사람이라면 알아서 채워 넣던 맥락을, 이제는 빠짐없이 적어두어야 합니다. 명시하지 않은 것은 그냥 없는 것과 같았습니다. 문서의 미덕이 ‘간결함’에서 ‘명시성’으로 조금씩 이동하고 있다는 걸, 이 사소한 정규화 작업이 알려주었습니다.
챗봇을 운영하며 든 생각을 조금 밀고 나가면, 라이터의 무게중심이 이동하고 있다는 결론에 닿습니다. 초안 생성은 이제 AI가 곧잘 합니다. 사람의 부가가치는 무엇이 참인지 판별하고, 무엇을 문서화할지 결정하고, 그 지식의 출처와 신선도를 관리하는 쪽에 남습니다.
이 답변의 근거가 어느 문서, 어느 버전인지 추적되지 않으면 AI 시대의 문서 품질은 보증할 방법이 없습니다. 오래 관심을 두었던 knowledge traceability가, 이제는 취향이 아니라 운영의 전제 조건이 되었습니다. 문서가 단순 참조 자료가 아니라 제품의 런타임 구성요소가 된 이상, 정확성과 최신성 관리는 콘텐츠 운영이라기보다 서비스 운영에 가까운 감각을 요구합니다. 문서에 SRE의 마음가짐이 필요해진 셈입니다.
그렇다고 사람이 읽는 글이 사라진다고는 생각하지 않습니다. 오히려 반대입니다. 조각 정보는 AI가 다 조립해주니까, 온보딩과 멘탈 모델을 세워주는 글, 왜 이렇게 설계했는지를 설득하는 글의 희소가치는 올라갑니다. 잘 쓴 개념 문서 한 편이 예전보다 더 귀해집니다.
소비의 형태는 ‘읽힌다’에서 ‘참조된다, 조립된다, 실행된다’로 넓어지는 중입니다. 그 안에서 저는 점점 글을 쓰는 사람이라기보다, 조직 지식의 신뢰성을 설계하는 사람에 가까워지고 있습니다. 작은 챗봇 하나가 알려준, 생각보다 큰 변화였습니다.
그리고 이렇게 한 편의 글로 남겨둡니다. 저라는 테크니컬 라이터가 AI 시대에 살아남을 근거를, 또 하나 조용히 쌓아 올리면서.
]]>브라우저 북마크와 스프레드시트로 시작했다가 금방 한계가 왔습니다. “이 주장 근거가 어느 문서 몇 페이지였지?”를 보고서 쓸 때마다 다시 뒤지고 있었거든요. 그래서 리서치 자체를 파이프라인으로 만들었습니다. 그 결과물이 AI Infrastructure Research Portal입니다.
보고서에 들어가는 문장 하나하나가 “어느 소스에서 왔는지” 즉시 확인 가능해야 한다는 걸 첫 번째 원칙으로 삼았습니다. 그래서 자료 수집을 단계별 CSV 파이프라인으로 쪼갰습니다.
url_candidates.csv 수집 후보 URL (검색 쿼리 기반 수집)
↓ 사람이 승인
url_registry.csv 승인된 URL 레지스트리
↓ 다운로드
download_manifest.csv 실제 받아진 파일 기록
↓ 텍스트 추출
source_index.csv 포털에 노출되는 소스 인덱스
↓ 가공
summaries.csv / insights.csv / knowledge_graph.csv
핵심은 후보와 확정 사이에 사람의 승인 단계를 둔 것입니다. 검색으로 긁어온 URL을 그대로 코퍼스에 넣으면 품질이 무너집니다. 후보 목록을 훑고 승인한 것만 다운로드·추출되도록 하니, 코퍼스에 있는 자료는 전부 “누군가 한 번은 눈으로 보고 통과시킨 것”이라는 보장이 생겼습니다.
메타데이터 저장소로 DB가 아니라 CSV 파일들을 썼습니다. 일부러 선택한 것인데, 리서치 데이터에는 CSV가 의외로 잘 맞았습니다.
물론 공짜는 아닙니다. 참조 무결성을 지켜주는 DB가 없으니 데이터가 조용히 어긋납니다. 그래서 포털에 Data Health Check 페이지를 만들어 URL 누락, 제목 누락, 카테고리 누락을 상시 점검하게 했습니다. 무결성을 스키마로 강제하는 대신, 대시보드로 드러나게 한 셈입니다.
수집·가공은 스크립트가 하지만, 열람은 팀이 해야 합니다. UI는 Streamlit으로 만들었습니다. 프론트엔드 코드 없이 파이썬만으로 데이터 앱을 만들 수 있어서, 포털의 첫 버전은 하루 만에 나왔습니다.
배포는 systemd + nginx 리버스 프록시로 사내 서버에 상시 구동시켰고, daily_update.sh로 갱신을 돌립니다. 처음엔 Render 같은 외부 호스팅도 검토했지만 내부 자료 특성상 사내 서버로 정리했습니다. 한 가지 삽질 공유: Streamlit 앞에 프록시를 두면서 enableCORS=false를 넣었다가 XSRF 보호와 충돌해서 뺐습니다. 최신 Streamlit은 이 설정을 알아서 처리하니 굳이 만지지 않는 게 낫습니다.
만들고 보니 가장 공들인 부분은 코드가 아니라 카테고리 체계였습니다. power, cold_climate_cooling, fiber 같은 인프라 축과 korea_ai_demand, korea_dr_backup, apac_customer_target 같은 고객 축을 분리해서 21개 카테고리로 정리했는데, 이 구조가 사실상 보고서의 목차이자 논증 구조가 됐습니다. 카테고리별로 자료가 몇 건인지 보이니 “여기는 근거가 얇다”는 것도 바로 드러나고요.
리서치 도구를 만든다는 건 결국 “무엇을 알아야 하는가”를 데이터 구조로 먼저 써보는 일이라는 걸 배웠습니다.
이 포털 덕분에 최종 보고서를 쓸 때 Evidence Matrix(주장-근거 매트릭스) 방식으로 작업할 수 있었습니다. 주장마다 소스 인덱스의 ID를 달아두면, 검토자가 “이거 근거 뭐예요?”라고 물을 때 원문 URL까지 두 클릭이면 도달합니다. 테크니컬 라이터로서 가장 만족스러운 부분이 바로 이 지점이었습니다 — 문서의 신뢰도는 문장이 아니라 추적 가능성에서 나온다는 것.
]]>.dwg 파일로 옵니다. 문제는 이 포맷이 비공개라는 것, 그리고 도면 안의 텍스트가 중국어라는 것이었습니다. “AutoCAD 없이, 오픈소스만으로 DWG를 읽고 → 중국어를 한국어로 번역하고 → 전압 같은 전기 구성까지 검증할 수 있을까?”라는 질문에서 시작한 프로젝트가 AttoGrid입니다.
몇 달간 실제 도면(AutoCAD 2007, 액침냉각·소방·냉난방 전기 도면, 4.8 MB)으로 검증하며 v1.0.0까지 온 과정을 정리해 봅니다.
오픈소스 DWG 라이브러리는 사실상 LibreDWG 하나입니다. 읽기 경로는 두 가지가 있는데, 실제 도면으로 비교해 보니 결과가 갈렸습니다.
| 경로 | 결과 |
|---|---|
dwg2dxf로 DXF 변환 후 파싱 |
복잡한 실도면에서 BLOCK_HEADER 에러로 DXF가 잘림 |
dwgread -O JSON으로 덤프 후 직접 파싱 |
115,547개 객체 전부 보존 |
교훈: 중간 포맷 변환을 거치지 말고, 원본에서 가장 가까운 덤프를 직접 파싱하라. DXF 변환은 도구의 지원 범위를 벗어나는 객체를 만나면 조용히 잘라먹지만, JSON 덤프는 일단 다 뱉어놓고 파싱을 내 쪽에서 통제할 수 있습니다.
도면에서 220V 같은 전압 텍스트를 뽑아 검증하려고 보니, MTEXT 엔티티의 값이 이렇게 생겼습니다.
{\Fxx|c0;220V\F..;电源线}
전압값과 중국어 라벨이 폰트 전환 코드(\F...;) 사이에 끼어 있는 겁니다. 그대로 정규식을 돌리면 아무것도 안 잡힙니다. MTEXT 포맷 코드를 걷어내는 clean_mtext() 정제 단계를 파이프라인 맨 앞에 두고 나서야 텍스트 추출·번역·전압 검증이 전부 제대로 동작했습니다. CAD 데이터를 다룬다면 “텍스트가 곧 텍스트가 아니다”라는 걸 기억해 둘 만합니다.
중→한 번역은 상황에 따라 요구가 달랐습니다. 인터넷이 되는 환경에선 DeepL이 품질이 좋고, 폐쇄망에선 오프라인 엔진이 필요하고, 로컬 GPU가 있으면 LLM(Ollama/vLLM)을 쓰고 싶고. 그래서 번역기를 인터페이스로 추상화하고 엔진을 선택하게 했습니다.
여기에 电源线 → 전원선 같은 전문용어 사전을 앞단에 두어 도메인 용어는 엔진과 무관하게 일관되게 번역되도록 했습니다. 번역 결과는 도면 SVG 위에 오버레이로 얹어서, 원본과 번역본을 버튼 하나로 오가며 볼 수 있습니다.
처음엔 PNG로 렌더해서 이미지 팬/줌을 했는데, 도면은 확대해서 보는 물건이라 금방 픽셀이 깨졌습니다. 최종적으로는 SVG의 viewBox를 직접 조작하는 팬/줌으로 바꿨습니다. 벡터라 아무리 확대해도 선명하고, non-scaling-stroke로 선 굵기도 줌 레벨과 무관하게 유지됩니다. 여기에 얹은 기능들:
DWG 쓰기(저장)는 오픈소스로는 불안정해서 일찍 포기했습니다. 대신 편집 결과를 DXF/JSON으로 저장하는 것으로 범위를 정했습니다. 기능 표에 ⛔를 명시적으로 남겨두는 것 — 안 되는 걸 되는 척하지 않는 것도 도구의 신뢰성이라고 생각합니다.
데스크톱 앱(pywebview)과 웹 서버 모드(Flask + nginx), CLI까지 한 코드베이스에서 돌아가는 v1.0.0을 릴리스했습니다. 비공개 바이너리 포맷, 폰트 코드에 묻힌 텍스트, 폐쇄망 번역 같은 제약이 겹친 프로젝트였지만, “실제 파일로 일찍, 자주 검증한다”는 원칙 덕분에 잘못된 경로(DXF 변환)를 초반에 버릴 수 있었던 게 가장 컸습니다.
]]>
The easiest way to make your first post is to edit this one. Go into /_posts/ and update the Hello World markdown file. For more instructions head over to the Kiko Now repository on GitHub.
]]>Lorem ipsum dolor sit amet, test link adipiscing elit. This is strong. Nullam dignissim convallis est. Quisque aliquam. This is emphasized. Donec faucibus. Nunc iaculis suscipit dui. 53 = 125. Water is H2O. Nam sit amet sem. Aliquam libero nisi, imperdiet at, tincidunt nec, gravida vehicula, nisl. Underline. Maecenas ornare tortor. Donec sed tellus eget COPY filename sapien fringilla nonummy. Mauris a ante. Suspendisse quam sem, consequat at, Dinner’s at 5:00. commodo vitae, feugiat in, nunc. Morbi imperdiet augue mark element quis tellus.
Lorem ipsum dolor sit amet, test link adipiscing elit. Nullam dignissim convallis est. Quisque aliquam.
| Header1 | Header2 | Header3 |
|---|---|---|
| cell1 | cell2 | cell3 |
| cell4 | cell5 | cell6 |
| cell1 | cell2 | cell3 |
| cell4 | cell5 | cell6 |
| Foot1 | Foot2 | Foot3 |
#container {
float: left;
margin: 0 -240px 0 0;
width: 100%;
}
<div id="awesome">
<p>This is great isn't it?</p>
</div>
탄핵소추의 의결을 받은 자는 탄핵심판이 있을 때까지 링크 그 권한행사가 정지된다. 제2항과 제3항의 처분에 대하여는 굵게 법원에 제소할 수 없다. 선거와 국민투표의 공정한 관리 기울임 및 정당에 관한 사무를 처리하기 위하여 53 = 125 선거관리위원회를 둔다. 국무총리는 대통령을 보좌하며, H2O 행정에 관하여 대통령의 명을 받아 행정각부를 통할한다. 정당은 법률이 정하는 바에 의하여 밑줄 국가의 보호를 받으며, 국가는 법률이 정하는 바에 의하여 파일명 정당운영에 필요한 자금을 보조할 수 있다. 모든 국민은 종교의 자유를 가진다. 국회의원은 법률이 정하는 직을 겸할 수 없다. 감사원은 가운데 줄 세입·세출의 결산을 매년 검사하여 대통령과 차년도국회에 형광펜 그 결과를 보고하여야 한다.
나는 헌법을 준수하고 국가를 보위하며 조국의 평화적 통일과 국민의 자유와 복리의 증진 및 민족문화의 창달에 노력하여 대통령으로서의 직책을 성실히 수행할 것을 국민 앞에 엄숙히 선서합니다. 모든 국민은 통신의 비밀을 침해받지 아니한다. 국회의원은 법률이 정하는 직을 겸할 수 없다. 국회는 헌법 또는 법률에 특별한 규정이 없는 한 재적의원 과반수의 출석과 출석의원 과반수의 찬성으로 의결한다. 가부동수인 때에는 부결된 것으로 본다.
| 상단1 | 상단2 | 상단3 |
|---|---|---|
| 셀1 | 셀2 | 셀3 |
| 셀4 | 셀5 | 셀6 |
| 셀1 | 셀2 | 셀3 |
| 셀4 | 셀5 | 셀6 |
| 하단1 | 하단2 | 하단3 |
#container {
float: left;
margin: 0 -240px 0 0;
width: 100%;
}
<div id="awesome">
<p>This is great isn't it?</p>
</div>
이 문서는 한글 Lorem Ipsum으로 생성되었습니다.
]]>| Character | Description |
|---|---|
| Ğ | Uppercase “G” with breve accent |
| İ | Uppercase dotted “I” |
| Ş | Uppercase “S” with cedilla |
| ğ | Lowercase “g” with breve accent |
| ı | Lowercase dotless “i” |
| ş | Lowercase “s” with cedilla |
Syntax highlighting is a feature that displays source code, in different colors and fonts according to the category of terms. This feature facilitates writing in a structured language such as a programming language or a markup language as both structures and syntax errors are visually distinct. Highlighting does not affect the meaning of the text itself; it is intended only for human readers.1
To modify styling and highlight colors edit /_sass/_highlighter.scss.
#container {
float: left;
margin: 0 -240px 0 0;
width: 100%;
}
<nav class="pagination" role="navigation">
{% if page.previous %}
<a href="{{ site.url }}{{ page.previous.url }}" class="btn" title="{{ page.previous.title }}">Previous article</a>
{% endif %}
{% if page.next %}
<a href="{{ site.url }}{{ page.next.url }}" class="btn" title="{{ page.next.title }}">Next article</a>
{% endif %}
</nav><!-- /.pagination -->
module Jekyll
class TagIndex < Page
def initialize(site, base, dir, tag)
@site = site
@base = base
@dir = dir
@name = 'index.html'
self.process(@name)
self.read_yaml(File.join(base, '_layouts'), 'tag_index.html')
self.data['tag'] = tag
tag_title_prefix = site.config['tag_title_prefix'] || 'Tagged: '
tag_title_suffix = site.config['tag_title_suffix'] || '–'
self.data['title'] = "#{tag_title_prefix}#{tag}"
self.data['description'] = "An archive of posts tagged #{tag}."
end
end
end
<nav class="pagination" role="navigation">
{% if page.previous %}
<a href="{{ site.url }}{{ page.previous.url }}" class="btn" title="{{ page.previous.title }}">Previous article</a>
{% endif %}
{% if page.next %}
<a href="{{ site.url }}{{ page.next.url }}" class="btn" title="{{ page.next.title }}">Next article</a>
{% endif %}
</nav><!-- /.pagination -->
An example of a Gist embed below.
]]>Portland in shoreditch Vice, labore typewriter pariatur hoodie fap sartorial Austin. Pinterest literally occupy Schlitz forage. Odio ad blue bottle vinyl, 90’s narwhal commodo bitters pour-over nostrud. Ugh est hashtag in, fingerstache adipisicing laboris esse Pinterest shabby chic Portland. Shoreditch bicycle rights anim, flexitarian laboris put a bird on it vinyl cupidatat narwhal. Hashtag artisan skateboard, flannel Bushwick nesciunt salvia aute fixie do plaid post-ironic dolor McSweeney’s. Cliche pour-over chambray nulla four loko skateboard sapiente hashtag.
Vero laborum commodo occupy. Semiotics voluptate mumblecore pug. Cosby sweater ullamco quinoa ennui assumenda, sapiente occupy delectus lo-fi. Ea fashion axe Marfa cillum aliquip. Retro Bushwick keytar cliche. Before they sold out sustainable gastropub Marfa readymade, ethical Williamsburg skateboard brunch qui consectetur gentrify semiotics. Mustache cillum irony, fingerstache magna pour-over keffiyeh tousled selfies.
In pug Portland incididunt mlkshk put a bird on it vinyl quinoa. Terry Richardson shabby chic +1, scenester Tonx excepteur tempor fugiat voluptate fingerstache aliquip nisi next level. Farm-to-table hashtag Truffaut, Odd Future ex meggings gentrify single-origin coffee try-hard 90’s.
Incididunt umami sriracha, ethical fugiat VHS ex assumenda yr irure direct trade. Marfa Truffaut bicycle rights, kitsch placeat Etsy kogi asymmetrical. Beard locavore flexitarian, kitsch photo booth hoodie plaid ethical readymade leggings yr.
Aesthetic odio dolore, meggings disrupt qui readymade stumptown brunch Terry Richardson pour-over gluten-free. Banksy american apparel in selfies, biodiesel flexitarian organic meh wolf quinoa gentrify banjo kogi. Readymade tofu ex, scenester dolor umami fingerstache occaecat fashion axe Carles jean shorts minim. Keffiyeh fashion axe nisi Godard mlkshk dolore. Lomo you probably haven’t heard of them eu non, Odd Future Truffaut pug keytar meggings McSweeney’s Pinterest cred. Etsy literally aute esse, eu bicycle rights qui meggings fanny pack. Gentrify leggings pug flannel duis.
Fashion axe hella gastropub lo-fi kogi 90’s aliquip +1 veniam delectus tousled. Cred sriracha locavore gastropub kale chips, iPhone mollit sartorial. Anim dolore 8-bit, pork belly dolor photo booth aute flannel small batch. Dolor disrupt ennui, tattooed whatever salvia Banksy sartorial roof party selfies raw denim sint meh pour-over. Ennui eu cardigan sint, gentrify iPhone cornhole.
Whatever velit occaecat quis deserunt gastropub, leggings elit tousled roof party 3 wolf moon kogi pug blue bottle ea. Fashion axe shabby chic Austin quinoa pickled laborum bitters next level, disrupt deep v accusamus non fingerstache.
Tote bag asymmetrical elit sunt. Occaecat authentic Marfa, hella McSweeney’s next level irure veniam master cleanse. Sed hoodie letterpress artisan wolf leggings, 3 wolf moon commodo ullamco. Anim occupy ea labore Terry Richardson. Tofu ex master cleanse in whatever pitchfork banh mi, occupy fugiat fanny pack Austin authentic. Magna fugiat 3 wolf moon, labore McSweeney’s sustainable vero consectetur. Gluten-free disrupt enim, aesthetic fugiat jean shorts trust fund keffiyeh magna try-hard.
Actually salvia consectetur, hoodie duis lomo YOLO sunt sriracha. Aute pop-up brunch farm-to-table odio, salvia irure occaecat. Sriracha small batch literally skateboard. Echo Park nihil hoodie, aliquip forage artisan laboris. Trust fund reprehenderit nulla locavore. Stumptown raw denim kitsch, keffiyeh nulla twee dreamcatcher fanny pack ullamco 90’s pop-up est culpa farm-to-table. Selfies 8-bit do pug odio.
Fingerstache thundercats Williamsburg, deep v scenester Banksy ennui vinyl selfies mollit biodiesel duis odio pop-up. Banksy 3 wolf moon try-hard, sapiente enim stumptown deep v ad letterpress. Squid beard brunch, exercitation raw denim yr sint direct trade. Raw denim narwhal id, flannel DIY McSweeney’s seitan. Letterpress artisan bespoke accusamus, meggings laboris consequat Truffaut qui in seitan. Sustainable cornhole Schlitz, twee Cosby sweater banh mi deep v forage letterpress flannel whatever keffiyeh. Sartorial cred irure, semiotics ethical sed blue bottle nihil letterpress.
Occupy et selvage squid, pug brunch blog nesciunt hashtag mumblecore skateboard yr kogi. Ugh small batch swag four loko. Fap post-ironic qui tote bag farm-to-table american apparel scenester keffiyeh vero, swag non pour-over gentrify authentic pitchfork. Schlitz scenester lo-fi voluptate, tote bag irony bicycle rights pariatur vero Vice freegan wayfarers exercitation nisi shoreditch. Chambray tofu vero sed. Street art swag literally leggings, Cosby sweater mixtape PBR lomo Banksy non in pitchfork ennui McSweeney’s selfies. Odd Future Banksy non authentic.
Aliquip enim artisan dolor post-ironic. Pug tote bag Marfa, deserunt pour-over Portland wolf eu odio intelligentsia american apparel ugh ea. Sunt viral et, 3 wolf moon gastropub pug id. Id fashion axe est typewriter, mlkshk Portland art party aute brunch. Sint pork belly Cosby sweater, deep v mumblecore kitsch american apparel. Try-hard direct trade tumblr sint skateboard. Adipisicing bitters excepteur biodiesel, pickled gastropub aute veniam.
]]>