pi-fluent-korean

pi 가 명확한 한국어로 응답하게 만드는 서술 지침 패키지입니다.

snflkd/fluent-korean 의 지침 본문을 그대로 사용하되, Claude Code 의 output-style 대신 pi 의 확장(extension)과 스킬(skill) 형태로 다시 구현했습니다.

무엇을 해결하는가

LLM 은 토큰을 절약하도록 조정되어 있어서, 한국어를 사용할 때 조사와 어미를 생략하고 명사구를 나열하는 문장을 자주 생성합니다. 코딩 에이전트에서는 그러한 경향이 더 강하게 나타납니다. 그러면 사용자가 보고 내용을 이해하는 데 더 많은 노력을 들여야 하고, 한국어로 작성된 산출물의 완성도도 함께 낮아집니다.

이 패키지는 그런 문장을 만들지 않도록, 지침을 사전에 시스템 프롬프트에 넣습니다.

저장 시점 다름 → 저장하는 시점이 서로 다릅니다
발행 시 이력 기록 → 발행할 때 이력을 기록합니다
이건 기존 동작 → 이것은 기존에도 동일하게 동작하던 부분입니다

설치

pi install npm:pi-fluent-korean

설치하면 확장이 곧바로 켜지고, 그다음 턴부터 지침이 적용됩니다. 프로젝트 단위로만 쓰려면 -l 을 붙이면 됩니다.

pi install -l npm:pi-fluent-korean

설치하지 않고 한 번만 시험해보려면 다음과 같이 실행합니다.

pi -e npm:pi-fluent-korean

사용법

확장이 켜져 있으면 별도 조작 없이 모든 턴에 지침이 적용됩니다. 푸터에 한국어:coding 처럼 현재 상태가 표시됩니다.

/fluent-korean 명령으로 상태를 바꿀 수 있습니다.

명령	동작
/fluent-korean	선택 메뉴를 표시합니다.
/fluent-korean status	지금 적용하고 있는 판이 무엇인지 알려줍니다.
/fluent-korean coding	코딩 작업용 판으로 변경합니다.
/fluent-korean not-coding	코드를 직접 변경하지 않는 작업용 판으로 변경합니다.
/fluent-korean off	지침 적용을 중단합니다.

명령으로 바꾼 값은 ~/.pi/agent/fluent-korean.json 에 저장되므로 다음 세션에도 유지됩니다.

두 가지 판

원본과 동일하게 두 가지 판을 제공합니다. 두 판의 차이는 서브에이전트와 관련된 조항 하나뿐입니다.

• coding : 서브에이전트에게 한국어 프롬프트를 전달할 때에도 지침을 점검하라는 조항이 들어 있습니다. 코딩 작업에 사용하세요.
• not-coding : 그 조항이 들어 있지 않습니다. pi 가 코드를 직접 변경하지 않는 작업에 사용하세요.

원본은 output-style 이라서 Claude Code 의 코딩 지침을 유지할지 여부까지 결정했지만, 이 패키지는 pi 의 시스템 프롬프트를 대체하지 않고 뒤에 덧붙이기만 하므로 pi 자체의 코딩 지침은 어느 판을 고르든 그대로 남아 있습니다.

설정

설정은 다음 순서로 겹쳐서 읽어들이며, 뒤에 오는 설정이 앞의 설정을 덮어씁니다.

1. ~/.pi/agent/fluent-korean.json (전역)
2. <프로젝트>/.pi/fluent-korean.json (프로젝트)
3. 환경 변수 PI_FLUENT_KOREAN (off / coding / not-coding)

{
  "enabled": true,
  "variant": "coding",
  "append": "- 사용자를 '사용자님'이라고 호칭하고, 사용자께 높임말을 사용합니다."
}

append 에 기재한 텍스트는 지침 본문 뒤에 그대로 추가됩니다. 원본 저장소의 세부 동작 단락 에 있는 블록들을 여기에 붙여넣으면 됩니다. 예를 들어 다음과 같은 조항들을 추가할 수 있습니다.

• - 항상, 한국어로 사고하고, 한국어로 보고하고, 한국어로 출력합니다.
• - 답변을 사용자에게 출력하기 직전에, 위의 지침들에 어긋난 부분을 반드시 점검하고 수정한 후에 출력합니다.
• - 한국어로 출력되는 모든 결과물에도 이 지침들을 적용합니다.

스킬

확장을 끄고 필요할 때만 지침을 적용하려는 경우, 또는 이미 작성한 한국어 문장을 교정하려는 경우에는 fluent-korean 스킬을 사용합니다. "한국어 다듬어줘" 와 같은 요청을 받으면 pi 가 스스로 판단하여 이 스킬을 호출합니다.

확장과 스킬은 같은 지침 본문(guidelines/)을 읽으므로 서로 어긋나지 않습니다. 둘 다 켜 두어도 문제가 발생하지는 않지만, 확장이 켜져 있으면 지침이 이미 적용되어 있으므로 스킬을 따로 호출할 이유는 거의 없습니다.

확장과 스킬 중에서 하나만 사용하려면 pi config 에서 개별적으로 끌 수 있습니다.

유의할 점

• 토큰을 조금 더 사용합니다. 생략되었던 문장 성분을 복원하므로 응답 토큰이 늘어나고, 지침 본문도 시스템 프롬프트에서 일정 분량을 차지합니다.
• 지침이 기대한 만큼 지켜지지 않을 수 있습니다. 대화가 길게 이어질수록, 그리고 다른 지시가 많을수록 그러한 경향이 강해집니다. 이럴 때에는 지침 자체를 수정하기보다 append 에 점검 조항을 추가하시는 편이 낫습니다.
• 지침은 코드, 코드 주석, 커밋 메시지, 인용문에는 적용되지 않습니다. 이 경계는 지침 본문에 명시되어 있습니다.
• 다만 그 경계를 옳게 판단하고도, 코드 주석에서 쓰던 어휘를 사용자에게 보고하는 문장으로 그대로 옮겨 적는 경우가 있습니다. 보고문은 지침이 적용되는 자리이므로 이때는 일반적인 어휘로 바꾸어야 합니다. 자세한 사례는 스킬 문서에 정리해 두었습니다.
• 지침 본문은 요약하지 않는 것을 권장합니다. 조항마다 붙은 예시가 있어야 그 조항이 어떤 동작을 의도했는지 파악할 수 있기 때문입니다.

라이선스

이 패키지는 MIT License 를 따릅니다. 지침 본문의 출처와 원본 라이선스는 NOTICE.md 에 정리해 두었습니다.