# pi-fluent-korean

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

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

## 무엇을 해결하는가

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

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

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

## 설치

```bash
pi install npm:pi-fluent-korean
```

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

```bash
pi install -l npm:pi-fluent-korean
```

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

```bash
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`)

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

`append` 에 기재한 텍스트는 지침 본문 뒤에 그대로 추가됩니다.
원본 저장소의 [세부 동작 단락](https://github.com/snflkd/fluent-korean#세부-동작---저는-claude가-이랬으면-좋겠어요)
에 있는 블록들을 여기에 붙여넣으면 됩니다. 예를 들어 다음과 같은 조항들을 추가할 수 있습니다.

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

## 스킬

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

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

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

## 유의할 점

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

## 라이선스

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