mrgnhnt96/impa

impa은(는) 무엇을 하나요?

개발자나 에이전트가 실행할 수 있고 코드와 일치하는 기술 문서를 작성합니다. 목표는 독자의 작업에 맞게 정확하고 최신이며 완전하고, 찾기 쉬우며, 작동하는 예제를 포함하고, 명확하고 직접적이며, 필요한 이상으로 길지 않은 문서를 만드는 것입니다.

한 라운드는 사용자가 요청한 하나의 작업입니다. 모든 라운드는 요청 없이도 리뷰로 끝납니다.

단계

1. 프로젝트 읽기

무언가를 작성하기 전에 먼저 읽습니다:

• 프로젝트에 있는 경우 .impa/plan.md
• 문서: README, docs/, 사이트 소스 및 설정, 변경 로그, 기여 가이드 및 지침 파일. 생성기와 CI의 문서 검사를 기록합니다.
• 독자가 접근할 코드: 진입점, 명령어 파서, 설정 스키마, 환경 변수, 오류 메시지, 공개 API 및 매니페스트.

프로젝트 유형(라이브러리, CLI, 서비스, 최종 사용자 앱, 내부 도구)과 에이전트 포함 문서 독자를 파악합니다. 프로젝트가 답할 수 없는 것에 대해서만 사용자에게 질문합니다.

프로젝트의 문서 도구를 유지합니다. 도구가 없으면 일반 Markdown 파일을 사용합니다.

2. 문서 유형 선택

reference/doc-types.md를 읽습니다. 이 프로젝트 유형에 필요한 행부터 시작하고, 트리거가 발생한 경우에만 트리거된 행을 추가하며, 거기서 멈춥니다. 한 페이지는 한 가지 작업을 수행합니다. 사용자가 한 페이지를 요청했다면 그 페이지를 작성하고 다른 것은 추가하지 않습니다.

사용자가 요청하지 않은 문서를 재구성하지 마십시오.

3. 계획 유지

프로젝트에 .impa/plan.md를 작성하거나 업데이트합니다. 이것은 다음 라운드가 읽는 것입니다:

# 문서 계획

프로젝트 유형: CLI
독자: CLI를 사용하는 개발자 및 이 레포지토리에서 작업하는 코딩 에이전트
문서 도구: 일반 Markdown
예제 증명: rung 3

## 페이지

| 페이지 | 유형 | 역할 | 독자 |
| --- | --- | --- | --- |
| README.md | README | 무엇인지와 시작 방법을 설명 | 도착하는 사람 |

## 하우스 스타일

제목 표기법, 작업 제목 형식, 축약형, "we", 플레이스홀더 형식, `$` 프롬프트. 프로젝트가 이미 사용하는 방식과 일치시킵니다.

## 사람을 기다리는 중

## 교훈

계획은 페이지와 선택을 담습니다. 그 이유는 계획에 넣지 마십시오. 리뷰어가 계획을 읽기 때문입니다.

4. 규칙에 따라 작성

프로젝트에 문서가 있으면 먼저 review/round.md의 '편집 전'에 따라 복사합니다. 라운드의 diff는 해당 복사본에서 비롯됩니다.

먼저 reference/principles.md를 읽은 다음, 작업에 필요한 것을 읽습니다. 작은 편집은 필요한 것만 읽습니다.

읽을 문서	시기
structure.md, wording.md, leave-out.md	작성하는 모든 페이지
examples.md	코드가 있는 모든 페이지
accuracy.md	확인 전 및 생성된 레퍼런스 설정 시
agent-readers.md	지침 파일, 스킬, 도구 설명, 에이전트가 가져오는 사이트

audit.md와 sources.md는 작성용이 아닙니다. 첫 번째는 impa audit의 빌드 목록이고, 두 번째는 인용을 보관합니다.

이러한 규칙이 존재하는 이유(함정):

• 답변 우선. 페이지는 한 문장으로 무엇을 하는지로 시작합니다. 그 다음 일반적인 경우, 그 다음 에지 케이스.
• 짧다는 것은 불필요한 단어가 없다는 뜻이며, 다른 것은 없습니다. 서문, 역사 및 반복을 제거합니다. 기본값, 제한, 오류, 전제 조건 및 예제는 유지합니다: leave-out.md의 유지 목록은 이를 제거하면 독자에게 해가 되기 때문입니다.
• 생성 가능한 것은 생성합니다 (A1). 플래그, 시그니처, 기본값 및 스키마는 도구가 코드에서 생성할 수 있는 것입니다. 수동으로 입력하지 마십시오. 프로젝트의 생성기를 사용하거나, 생성기가 도움이 될 것이라고 사용자에게 알립니다.
• 각 사실에 대해 하나의 출처. 한 번만 명시하고 링크합니다.
• 하우스 스타일 일치. 일관성이 최우선입니다. 규칙 세트의 표현 선택은 하우스 스타일이 없는 프로젝트의 기본값입니다.
• 머리말: 문서 도구가 허용하는 경우 docs 폴더의 페이지에 type (T2)을 부여합니다. README, 변경 로그 또는 지침 파일에는 머리말을 절대 추가하지 마십시오: GitHub는 첫 문장 위에 표로 표시하고, 도구는 해당 파일을 전체적으로 읽습니다.
• 지침 파일에는 에이전트가 레포지토리에서 알아낼 수 없는 것만 포함합니다 (G1). 사람이 생성된 파일을 커밋하기 전에 편집해야 하므로 (G11), 사용자에게 알립니다.
• 절대 가짜 정보를 만들지 마십시오. 찾을 수 없는 사실은 작성하지 않는 문장입니다. 스텁, 빈 제목 또는 TODO를 남기지 마십시오 (T4). 페이지가 해당 값 없이 작동할 수 없는 경우 API_URL_TODO와 같은 명백한 센티넬을 사용하고 계획의 사람을 기다리는 중에 추가합니다.

5. 코드와 대조하여 확인

페이지가 명시하는 각 항목을 하나씩, 그것이 설명하는 코드와 대조하여 확인합니다. 안전한 경우 실행해 봅니다. 읽는 것만으로는 실행이 보여주는 것을 놓칠 수 있기 때문입니다.

페이지가 명시하는 것	확인 대상
명령어, 하위 명령어 또는 플래그	파서의 소스 및 실제 --help
경로 또는 파일	트리. 단, 페이지가 독자가 생성한다고 명시하는 경우는 제외
기본값, 제한, 단위, 순서, 부작용	이를 설정하는 코드 라인. 도움말 텍스트, 주석 또는 이전 문서는 제외
환경 변수, 설정 키	코드가 이를 읽는 위치
오류 메시지	소스의 정확한 문자열
버전, 지원 플랫폼	매니페스트 또는 CI 설정
API 이름, 시그니처, 반환 값	정의
예제	프로젝트의 증명 수준까지 컴파일하거나 실행 (examples.md)
설치, 빠른 시작, 튜토리얼	임시 폴더의 깨끗한 상태에서 모든 단계를 따름

실제 데이터, 실제 돈 또는 공유 시스템을 건드리는 것은 절대 실행하지 마십시오. 실행하지 않은 것을 알립니다.

기존 문서는 증거가 아닙니다. 유지하는 문서라도 마찬가지입니다. 확인할 수 없는 주장은 제거되거나 보고되며, 신뢰에 기반하여 남겨두지 않습니다.

문서와 코드가 일치하지 않을 때, 코드가 버그일 수 있습니다. 코드가 하는 것을 작성하고, 사용자에게 알리며, 요청하지 않는 한 코드를 변경하지 마십시오.

6. Audit 실행

impa audit --dir <프로젝트>

실제 문제를 수정합니다. 명령어가 실패하거나 바이너리에 audit이 없는 경우, audit이 실행되지 않았다고 사용자에게 알리고 계속 진행합니다. 깨끗한 audit은 거의 증명하지 않습니다: 존재하는 이름을 확인할 뿐, 그 주변의 문장이 사실인지는 확인하지 않습니다. 깨끗한 실행을 위해 값을 위조하지 마십시오.

7. 라운드 리뷰

요청 없이 review/round.md를 따릅니다. 리뷰는 처음에는 전체 문서 세트를, 그 이후에는 diff와 그 diff가 영향을 미치는 부분을 다룹니다. 백그라운드에서 impa review를 통해 실행됩니다.

이 라운드에 대해 사용자가 명시적으로 요청한 경우에만 건너뛰고, 건너뛰었다고 보고합니다. 리뷰가 실행되기 전에 문서가 완료되었다고 말하지 마십시오.

review/method.md 또는 review/checklist.md를 읽지 마십시오. 리뷰어만 해당 파일을 로드합니다.

8. 보고

사용자에게 알립니다:

• 작성하거나 변경한 내용과 선택한 문서 유형.
• 확인할 수 없거나 실행하지 않은 사항.
• 문서와 코드가 일치하지 않은 부분과 그에 대해 취한 조치.
• 리뷰: 평결, 발견한 사항, 수정한 사항, 열려 있는 사항, 조치할 수 있는 사람 및 비용.

평결이 사람이 조치할 때까지 출시 불가라면 그렇게 시작합니다.

사용자가 요청하지 않는 한 커밋, 푸시 또는 게시하지 마십시오.

9. 학습

사용자가 무언가를 수정하거나, 라운드가 이 프로젝트의 함정을 보여줄 때, .impa/plan.md의 교훈에 추가합니다. 여기의 규칙이 모든 프로젝트에 대해 잘못된 경우 사용자에게 알립니다: 수정 사항은 한 프로젝트의 계획이 아닌 이 스킬에 속합니다.