Skip to content

hashgraph-online/awesome-codex-plugins / plugins/alpoxdev/hypercore/skills/hyper-issue

hyper-issue

Verified

Use this skill when the user wants a confirmed finding or a piece of decided work recorded as an implementation-ready issue, wants a fixed batch of open issues selected and grouped into disjoint work lanes, or names issue numbers such as `#1~3` to run as a batch. It investigates only enough to make the issue self-contained, writes the issue in English for a fresh agent with a machine-readable scope block, produces a batch manifest, and hands the lanes to the hyper orchestrator when work should follow. Do not use for implementing the work itself, for general documentation, or for a plan file.

rules/issue-contract.ko.md

View on GitHub
# Issue Contract

이슈 본문을 쓰기 전에 이 규칙을 사용한다. 분류, 증거 기준, 본문 언어, 필수 절, `hyper:` 블록, 중복 확인, 메타데이터, 쓰기 확인을 소유한다.

## 1. 분류

사용자가 쓴 단어가 아니라 요청된 동작으로 분류한다.

| Class | 쓰는 때 | 필요한 증거 |
|---|---|---|
| `bug` | 관측 동작이 기대와 다르거나 기존 불변식이 깨졌을 때 | 실패 재현 또는 로그 발췌, 그리고 경로와 줄로 고정한 원인 |
| `feature` | 사용자에게 보이는 새 동작이나 기존 동작의 실질적 확장 | 결정된 결과, 영향 표면, 해소된 미결 결정 |
| `task` | 유지보수, 리팩터, 문서, 테스트, 보강, 마이그레이션, 정리 | 현재 상태와 변경 경계 |

지목된 리비전에서 원인이 확인되지 않은 결함은 `bug`가 아니다. 확인하거나, 원인 줄에 `Assumption:`을 붙여 `bug`로 기록하고 무엇이 확인해 줄지 적는다. 원인 기준을 피하려고 확인되지 않은 결함을 `task`로 바꾸지 않는다.

두 항목을 독립적으로 구현하고 검증할 수 있으면 별도 이슈로 나눈다. 같은 의도된 결과, 같은 변경 경계, 같은 검증을 공유하면 한 이슈에 둔다.

## 2. 증거 기준

- 모든 사실 줄에 줄 위치가 붙은 경로, 출력이 붙은 명령, 또는 트래커 참조를 붙인다.
- "이상해 보인다"는 증거가 아니다. 확보한 실패가 증거다.
- 증상, 유발 조건, 전파 경로, 근본 원인을 구분한다.
- 비밀, 토큰, 개인정보, 고객 값을 본문에 옮기지 않는다. 가리고 무엇을 가렸는지 적는다.
- 원래 로그, 데이터베이스, 세션이 사라진 뒤에도 본문이 쓸 수 있어야 한다. 접근할 수 없는 사실은 최소 픽스처, 테스트 벡터, 정확한 로컬 설정으로 바꾼다.

## 2a. 본문 언어

이슈를 읽는 쪽은 이 대화를 볼 수 없는 새 세션의 에이전트다. 그 독자를 위해 쓴다.

- 대화와 실행 보고가 한국어여도 제목과 본문 전체는 영어로 쓴다. 인용한 오류 메시지, 로그 줄, UI 문자열은 원래 언어 그대로 둔다.
- 제목은 커밋 제목처럼 쓴다. 명령형이고, 선택적인 `type(scope):` 접두어 뒤는 소문자로 시작하며, 끝에 마침표가 없고, 72자 이하다(`fix(orders): return 409 on idempotency key replay`).
- 본문 줄은 경로, 심볼, 명령, 상태 코드 같은 구체 명사를 쓴 짧은 평서문이나 명령문으로 쓴다. 대화를 되가리키는 표현("아까 본 그것", "as discussed")을 쓰지 않는다.
- 추론은 `Assumption: <statement> - Confirm by: <check>`로 표시한다. 단락 전체를 흐리게 쓰지 않는다.
- 저장소의 이슈 템플릿이나 사용자의 명시적 지시가 다른 언어를 정하면 그 언어를 따르고, 그 선택을 실행 메모에 적는다.

## 3. 필수 절

모든 본문은 이 순서로, 이 정확한 영어 이름의 절을 갖는다.

1. `## What` - 무엇이 잘못됐는지 또는 무엇을 원하는지, 그리고 영향. 한 단락.
2. `## Evidence` - 경로, 명령, 출력, 로그. 가림 여부 명시.
3. `## Cause`(bug) 또는 `## Intended behavior`(feature, task) - 확인된 원인 또는 결정된 동작.
4. `## Scope` - 정확한 변경 경계, 그리고 `hyper:` 블록.
5. `## Out of scope` - 이 이슈가 의도적으로 하지 않는 일.
6. `## Acceptance` - 검토자가 실행할 수 있는 이분법 검사.
7. `## Verify` - 작업을 증명하는 그대로의 명령과 통과 모습.

관측할 수 없는 수용 기준은 수용 기준이 아니다. "잘 동작한다"는 수용 기준이 아니고 "`GET /api/x`가 200과 `status: ready`를 반환한다"가 수용 기준이다.

## 4. `hyper:` 블록

`## Scope` 안에 펜스 YAML 블록 하나를 증거로 손수 쓴다.

```yaml
hyper:
  touches:            # 이 이슈가 쓰는 경로 또는 글롭
    - src/api/retry.ts
  depends_on: []      # 먼저 반영되어야 하는 이슈 번호
  conflicts_with: []  # 같은 코드를 건드려 병렬 실행하면 안 되는 이슈 번호
  lane_hint: retry    # 쓰기 집합의 짧은 kebab-case 이름
  verify: "bun test src/api/retry.test.ts"
  size: s             # s | m | l, 변경 경계 기준
```

규칙:

- `touches`는 쓰기 집합이지 읽기 집합이 아니다. 맥락으로만 읽는 파일은 넣지 않는다.
- 여러 이슈가 고쳐야 하는 공유 파일은 그 모든 이슈가 나열하고, 명세는 그들을 의존 순서의 한 레인에 둔다.
- `depends_on`과 `conflicts_with`는 이슈 번호이며 추측이 아니다. 모르면 `[]`이고, 배치 단계가 `touches` 겹침으로 간선을 다시 도출한다.
- `verify`는 이미 있는 명령이거나 이 이슈가 만들고 이름을 밝힌 명령이다. "테스트 실행"은 안 된다.
- `size`가 `l`이면 배정 전에 나눠야 한다는 뜻이며 `## Scope`에 그렇게 적는다.

## 5. 중복 확인

1. 제목의 가장 구체적인 두 용어와 건드리는 경로로 질의 하나를 만들어 열린 이슈로 범위를 좁힌다.
2. 상위 결과의 제목만 보지 말고 본문을 읽는다.
3. 질의와 결과를 실행 노트에 기록한다.

| 결과 | 조치 |
|---|---|
| 열린 이슈가 같은 결과와 경계를 다룬다 | 새로 만들지 않고 그 이슈를 갱신하고 빠진 절만 채운다 |
| 열린 이슈가 일부만 다룬다 | 이 이슈를 만들고 본문에 `Refs #<n>`을 붙인다 |
| 열린 이슈가 완료로 닫혔다 | 대상 리비전에서 다시 확인하고, 결함이 사라졌으면 보고만 하고 만들지 않는다 |
| 일치 없음 | 만든다 |

중복 질의가 실패하거나 불완전하면 "중복 없음"으로 처리하지 않고 공백으로 보고한다.

## 6. 메타데이터

- 라벨, 타입, 필드는 증거가 값을 뒷받침하고 저장소가 이미 정의했을 때만 붙인다. 라벨 이름을 만들어 내지 않는다.
- `bug`는 버그 라벨이나 타입이 있으면 그것으로, `feature`와 `task`도 각자의 것으로 대응한다.
- 우선순위는 영향, 범위, 긴급도, 우회 가능성에서 나온다. 크기는 `## Scope`의 변경 경계에서 나온다.
- 불확실한 값을 생략하는 것이 맞고 추측은 틀렸다. 생략마다 사유를 실행 노트에 기록한다.

## 7. 쓰기

1. 본문을 임시 파일에 쓰고 경로로 넘겨 한 번만 생성하거나 갱신한다.
2. 기록을 다시 읽는다. 제목, 본문, 라벨, 상태, 번호.
3. 다시 읽은 본문을 의도한 본문과 비교한다. 불일치는 보고하고 조용히 받아들이지 않는다.
4. 쓰기가 실패했거나 결과가 불확실하면 재시도 전에 트래커를 읽어 조정한다. 같은 본문으로 두 번째 이슈를 만들지 않는다.

트래커를 쓸 수 없거나 쓰기 권한이 없으면 본문을 `.hyper/issues/<slug>/drafts/<n>-<slug>.md`에 저장하고 빠진 기능을 기록하며, 사용자가 실행할 정확한 명령을 보고한다.

## Sources

> 확인 2026-11-07.

| Claim | Source |
|---|---|
| 조사 우선 이슈 작성과 쓰기 전 중복 게이트 | [kdy1-scripts add-issue](https://github.com/kdy1/kdy1-scripts) |
| 태스크별 의존·충돌 메타데이터와 공유 파일 단일 소유자 | [automazeio/ccpm](https://github.com/automazeio/ccpm) |
| 독립 구현 단위마다 이슈 하나, 컨텍스트 하나 크기 | [MrLesk/Backlog.md](https://github.com/MrLesk/Backlog.md) |
| 결함으로 보고하기 전 지목된 리비전에서 원인 확인 | [kdy1-scripts add-issue](https://github.com/kdy1/kdy1-scripts) 원인 기준 |
| 이슈 제목과 본문을 새 세션 에이전트가 읽는 영어로, 커밋 메시지처럼 쓴다 | 사용자 지시, 2026-11-07 |

### 근거 등급

`LOCAL` - 절 목록과 `hyper:` 키 집합은 이 패키지의 설계다. 분류와 중복 규칙은 위 선행 사례를 각색했다.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 197kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 197kUpdated Claude CodeCodexVerifiedInstall