[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81112":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":13,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":15,"starSnapshotCount":15,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},81112,"hyper-waterfall","postmelee\u002Fhyper-waterfall","postmelee","A traceable, approval-driven methodology harness for AI pair programming.","",null,"JavaScript",47,6,1,0,5,12,15,2.54,"MIT License",false,"main",true,[],"2026-06-12 02:04:11","# Hyper-Waterfall\n\nEnglish | [한국어](README.ko.md) | [简体中文](README.zh-CN.md)\n\n![Hyper-Waterfall overview](docs\u002Fassets\u002Fhyper-waterfall.png)\n\n## A Methodology for Turning AI Pair Programming into a Traceable, Approvable Development Process\n\nHyper-Waterfall is not a way to tell AI, \"just build it.\" It puts AI's execution speed inside human planning, approval, verification, and reporting discipline so you get both fast implementation and a traceable development process.\n\nThe core is simple: **AI executes, humans decide the direction.** Work flows through Issue, branch, plan, Stage report, final report, and PR, with approval gates at the boundaries between steps.\n\n| Hyper-Waterfall Core | Meaning |\n|---|---|\n| Human decision ownership | Direction, scope, quality, and architecture decisions stay with the human. |\n| Approval gates | A human checks before source edits, stage transitions, final reporting, and PR creation. |\n| Externalized work memory | Context is left in Issues, plans, reports, PRs, and commit logs instead of only in chat. |\n| Staged execution | Large work is split into Stages, and every Stage includes verification and reporting. |\n| Resumable process | A new AI session or contributor can read repository documents and continue from the same context. |\n\n> [!IMPORTANT]\n> **Delegate execution to AI, but do not delegate decision ownership.**\n>\n> Hyper-Waterfall is not a tool that makes AI magically capable of anything. It is a set of rails that lets AI move quickly without making humans lose direction.\n\n## Why Hyper-Waterfall?\n\nAI's weakness is not a lack of execution power. Its weakness is that it can lose context or run quickly in the wrong direction. Hyper-Waterfall turns that weakness into workflow constraints and places AI's speed inside a development process humans can review.\n\n| Strength | Meaning |\n|---|---|\n| Knowledge captured as assets | Intent, plans, verification results, and decision rationale remain in `mydocs\u002F`, Issues, PRs, and commit logs, becoming input for the next task. |\n| Early risk detection | Humans check direction at the task plan, implementation plan, and Stage report boundaries, reducing late discovery of wrong direction after a large implementation. |\n| Automated role split | Humans decide direction, priority, quality, and architecture; AI handles repeated work such as exploration, implementation, verification, and documentation. |\n| Lightweight context | `1 Issue = 1 Task = 1 Branch = 1 Session` keeps sessions small while repository documents retain memory. |\n| Prompt guide alignment | Clear goals, sufficient context, output formats, verification criteria, and stop conditions are fixed by repository structure and templates. |\n\nHyper-Waterfall is a methodology harness that turns AI coding into a traceable and approvable development process by binding it to Issue, branch, plan, Stage report, final report, and PR.\n\nInstead of letting AI edit files immediately, it documents the task purpose, scope, and verification criteria first. Approval gates stand before source edits, stage transitions, final reports, and PR creation.\n\nAs a result, every task is documented, and decisions plus verification results remain in the repository. Even when chat context disappears, task intent and progress can be traced again, and another AI session or worker can resume from the same context.\n\n## Quick Start\n\n### Existing repository\n\nSend this one line to your AI coding tool.\n\n```text\nApply the Hyper-Waterfall methodology from https:\u002F\u002Fgithub.com\u002Fpostmelee\u002Fhyper-waterfall to this repository.\n```\n\n### New project\n\nWhen your project idea is ready to become a repository, create an empty GitHub or local repository first. Then send this prompt from that empty repository.\n\n```text\nI am starting a new project in this empty repository.\n\nApply the Hyper-Waterfall methodology from https:\u002F\u002Fgithub.com\u002Fpostmelee\u002Fhyper-waterfall to this repository first.\n\nIf a project brief or requirements draft is attached, use it for context only. Do not create product plans, architecture documents, or source code during adoption. After adoption, help me register the first product task as a separate GitHub Issue.\n```\n\nIn both paths, the AI starts from [`docs\u002Fagent-entrypoint.en.md`](docs\u002Fagent-entrypoint.en.md) and follows the adoption procedure. It must ask for approval before changing source files.\n\n| What the AI reports first | Content |\n|---|---|\n| Adoption mode | Whether this is a new adoption or an update to an existing Hyper-Waterfall installation. |\n| Change candidates | Which files it would create or modify, and whether placeholder substitution is needed. |\n| Approval request | The scope the task requester must approve before actual file changes. |\n\n### Language support\n\nThe default locale is `en`. Supported locale packs are `en`, `ko`, and `zh-CN`; missing locale sources are reported before fallback candidates are used.\n\n| Language | Locale |\n|---|---|\n| English | `en` |\n| Korean | `ko` |\n| Simplified Chinese | `zh-CN` |\n\nWhen using an AI coding tool, ask in the language you want to use. The AI reports the selected locale before changing files.\n\nTo check adoption from a terminal, pass the locale explicitly. Replace `en` with `ko` or `zh-CN` as needed.\n\n```sh\nnpx hyper-waterfall@0.3.0 init --repo . --locale en --dry-run\n```\n\nOn macOS, install the CLI with Homebrew if you run it often.\n\n```sh\nbrew install postmelee\u002Ftap\u002Fhyper-waterfall\nhyper-waterfall init --repo . --locale en --dry-run\n```\n\nThe `npx` and Homebrew CLI commands print lifecycle judgment only. Actual file changes still move through the approval workflow.\n\nAfter adoption, the AI proceeds according to the Hyper-Waterfall process. New users can simply ask the AI in natural language, such as `\"Implement this.\"`\n\n> Hyper-Waterfall lets anyone apply the method to a GitHub repository and makes multiple AI coding agents, including Codex and Claude Code, work under the same discipline.\n\n## Learn More About Hyper-Waterfall\n\n[When to Use](#when-to-use) ·\n[Compared with Conventional AI Coding](#compared-with-conventional-ai-coding) ·\n[What Changes Immediately](#what-changes-immediately) ·\n[Strengths of Hyper-Waterfall](#strengths-of-hyper-waterfall) ·\n[Workflow After Adoption](#workflow-after-adoption) ·\n[Target Repository Structure After Adoption](#target-repository-structure-after-adoption)\n\n## When to Use\n\nHyper-Waterfall focuses on keeping human control and traceability when AI is changing code quickly.\n\n| Good Fit | Poor Fit |\n|---|---|\n| You let an AI coding tool modify real source code, but want humans to approve scope and quality standards. | A one- or two-line change where plan and report overhead is larger than the change itself. |\n| Work must continue across multiple days, sessions, or agents. | Disposable prototypes where immediate experimentation matters more than traceability. |\n| PR reviewers need to see what changed, why it changed, and how it was verified. | Repositories that do not use GitHub Issue, branch, and PR workflows. |\n| You want to split large work by Issue, branch, and Stage so wrong direction is caught early. | Work where humans intend to accept AI output without review. |\n| New contributors or new AI sessions need to restart from repository documents alone. | Personal experiments where handoff or resumability does not matter. |\n\n> It is best suited for work where AI performs real source edits while humans must keep control over direction and quality. It can be too heavy when immediate experimentation matters more than traceability.\n\n## Compared with Conventional AI Coding\n\nThe core is not giving decision ownership to AI. It is putting AI's execution speed inside human approval, review, and documentation discipline. Humans decide direction and quality, while AI performs analysis, implementation, verification, and documentation quickly.\n\n> The difference is not whether you use AI, but which boundaries AI works inside. Conventional AI coding depends on the conversation flow; Hyper-Waterfall fixes task units, approval points, and artifact formats inside the repository.\n\n| Conventional AI Coding | After Applying Hyper-Waterfall |\n|---|---|\n| You say \"build this\" and AI edits files immediately. | Issue and task plan first define purpose, scope, and verification criteria. |\n| Scope keeps shifting during conversation. | The implementation plan splits work into Stages and execution stays inside the approved scope. |\n| It is hard to trace later which files AI changed and why. | Stage reports and commits record the reason, artifact, and verification result for each change. |\n| Context gets blurry as chat grows. | Work memory is externalized into `mydocs\u002F`, Issues, PRs, and commit logs. |\n| Wrong direction is discovered only after a large implementation. | The task requester approves or redirects at the task plan, implementation plan, and Stage boundaries. |\n| PR reviewers need to search through chat logs again. | The PR and reports show what changed, why it changed, and how it was verified. |\n\nThe human task requester keeps full ownership of direction, quality, and architecture decisions, while AI performs implementation at a speed and scale humans cannot reach alone.\n\n> [!IMPORTANT]\n> **Key difference: humans never stop thinking.**\n\n## What Changes Immediately\n\n1. **AI does not modify code arbitrarily.**\n   Source changes pass through a plan and approval gate first, so the task requester keeps control over direction.\n\n2. **Humans do not lose control.**\n   Approval gates stand before source edits, stage transitions, final reports, and PR creation. AI executes, but humans own direction and quality decisions.\n\n3. **You no longer need to search chat history for \"where did we stop?\"**\n   Issue, today's todo, task plan, Stage reports, final report, and PR automatically form the task timeline.\n\n4. **Work memory remains even when chat disappears.**\n   Intent, decisions, and verification results remain in `mydocs\u002F`, Issues, PRs, and commit logs. New sessions, new agents, and new contributors can restart from the same context.\n\n5. **Task-level work keeps context small and clear.**\n   The recommended operation is `1 Issue = 1 Task = 1 Branch = 1 Session`. When a task ends, the session closes; the next issue starts in a clean new session.\n\n6. **You can run multiple AI sessions in parallel.**\n   Independent Issues can run in separate `local\u002Ftask{N}` branches or separate worktrees. Context and change scope do not mix.\n\n7. **PR review becomes easier.**\n   The PR explains what changed, why it changed, which Stages were completed, and which verification ran. Reviewers read repository artifacts, not chat logs.\n\n8. **You reduce late discovery of wrong direction after a large implementation.**\n   Task plans, implementation plans, and Stage completion reports become quality gates reviewed by humans.\n\n9. **You keep the speed of vibe coding while recovering engineering discipline.**\n   You can build quickly while still explaining what was built, tracing where it went wrong, and handing it off at any point.\n\n10. **AI coding becomes a traceable development process instead of a \"vibe.\"**\n    Every task connects through Issue, branch, document, commit, and PR so it can be reviewed and handed off later.\n\n## Strengths of Hyper-Waterfall\n\nAI has two structural weaknesses.\n\n- It loses context when sessions grow long or tools change.\n- It can keep executing confidently even when the direction is wrong.\n\nThis repository turns those weaknesses into work constraints and creates immediately visible benefits along four axes.\n\n### 1. Every Task Becomes Documentation, and Documentation Becomes the Next Prompt — Knowledge Captured as Assets\n\n- Task intent, plans, stage-by-stage verification results, and decision rationale all accumulate as markdown files inside `mydocs\u002F`. They are not just records; they are **input for the next task**. When a model starts a new task, it reads past plans, reports, and decision records from the same repository and builds on them.\n- When continuing work, you can restore context from repository artifacts instead of relying on chat history. A new contributor or new AI session can start from the same baseline.\n\n> This has the same structure as connecting an Obsidian vault to an LLM and using a personal knowledge store as context. The difference is the nature of the vault. Obsidian stores general knowledge and ideas; `mydocs\u002F` is a **vault specialized for work history**, accumulating intent, plans, verification, artifacts, and troubleshooting by task. The process enforces it, so it stays complete and consistent.\n\n### 2. Direction Errors Are Caught at Gates Before Large Failures — Risk\n\n- Work follows `Issue -> branch -> task plan -> implementation plan -> Stage implementation, verification, and report -> final report -> Open PR`, and each gate requires task requester approval.\n- Instead of discovering \"the direction was wrong\" after a large implementation, it is caught early at the **task plan, implementation plan, and each Stage boundary, so sunk cost stays low.**\n- If Stage verification fails, recovery happens inside that Stage. If scope changes, the plan is updated and re-approved.\n\n### 3. Not \"Ask AI Nicely,\" but \"Make It Structurally Likely That AI Works Well\" — Automated Role Split\n\n- The task requester keeps responsibility for **direction, priority, architecture, and quality decisions**, while AI handles high-repetition work such as exploration, drafting, implementation, tests, reports, and PR body drafting. Every stage transition requires explicit approval from the task requester.\n- This repository **automates that split operationally**. Task management rules are separated into SKILLs so AI naturally follows what to do at each step, what artifacts to leave, and when to stop and hand control back to the human.\n- The work document formats naturally satisfy the core of official OpenAI and Anthropic prompting guides. Users do not need to study prompt engineering separately; AI works inside consistent central templates, clear context, staged thinking, and fixed output formats.\n\n### 4. Open and Close Sessions by Task — Lightweight Context\n\n- Hyper-Waterfall does not keep accumulating every work context in one AI session. The recommended operation is **`1 Issue = 1 Task = 1 Branch = 1 Session`**. One session owns one Issue, and when that task ends, the session ends too.\n- Each session reads only the current Issue, task plan, implementation plan, Stage reports, and related code. Old conversations and decisions from other tasks do not pollute current judgment, so **context stays small and clear.**\n- When a task ends, the result remains in `mydocs\u002F`, Issues, PRs, and commit logs instead of chat. The next task can start from a new session and still rebuild the same context from repository documents.\n- Independent Issues can run in parallel across multiple AI sessions using separate `local\u002Ftask{N}` branches or separate worktrees. Tasks that touch the same file or architecture decision should be ordered first.\n\n> AI sessions do not necessarily get smarter as they get longer. They often get blurrier. Hyper-Waterfall keeps sessions short and leaves memory in the repository.\n\n### 5. Result\n\nThese four parts are not separate features; they form one work loop. Work becomes documentation, wrong direction is filtered at gates, human and AI roles are split, and sessions stay small by task.\n\nAs a result, AI coding becomes a traceable, reviewable, and resumable development process inside the repository instead of a long chat.\n\n> [!NOTE]\n> This structure aligns with the official OpenAI and Anthropic prompting guides: clear instructions, sufficient context, output format constraints, verification criteria, long-term work memory, and agentic workflow control. See [Prompt Guide Alignment](#prompt-guide-alignment) for the detailed mapping.\n\n## Workflow After Adoption\n\nHyper-Waterfall works in **task** units.\n\n### Task Procedure\n\nEvery task follows this procedure **strictly**.\n\n```text\n1. Confirm or register a GitHub Issue\n2. Record today's todo (mydocs\u002Forders\u002F)\n3. Create task branch (local\u002Ftask{number})\n4. Write task plan -> [task requester approval]\n5. Write implementation plan -> [task requester approval]\n6. Implement by Stage\n7. Write Stage completion report -> [task requester approval]\n8. Repeat next Stage\n9. Write final result report -> [task requester approval]\n10. Update today's todo status\n```\n\n> Each `[approval]` point is a quality gate. Direction errors that code review alone cannot catch are caught during document review.\n\nDetailed procedure follows the [task workflow manual](templates\u002Flocales\u002Fen\u002Fmydocs\u002Fmanual\u002Ftask_workflow_guide.md). Branch and PR publication flow is described in the [Git workflow manual](templates\u002Flocales\u002Fen\u002Fmydocs\u002Fmanual\u002Fgit_workflow_guide.md).\n\n### Core SKILL Details\n\n| SKILL | When to Use | Main Artifacts |\n|---|---|---|\n| `task-register` | When a new task needs a GitHub Issue first | A GitHub Issue following the `task.yml` Issue Form structure, milestone and label candidates, and selection rationale |\n| `task-start` | When starting work on an approved issue | `local\u002Ftask{N}` branch, today's todo row, task plan based on `task_plan.md` |\n| `task-stage-report` | After one Stage is implemented and before moving to the next Stage | Stage report based on `stage_report.md`, Stage bundle commit, Stage verification result |\n| `task-final-report` | After all Stages are complete and just before publishing the PR | Final report based on `final_report.md`, today's todo completion update, Open PR |\n| `pr-merge-cleanup` | Immediately after a PR is actually merged | Issue close, `publish\u002Ftask{N}` remote deletion, local branch\u002Fworktree cleanup |\n| `external-pr-review` | When reviewing an external contributor PR | `mydocs\u002Fpr\u002F` review documents based on `external_pr_*` templates, verification result, recommendation (merge\u002Frequest changes\u002Fclose) |\n| `todo` | When creating or updating the today's todo board | `mydocs\u002Forders\u002Fyyyymmdd.md` table update based on `orders.md` |\n\nWhen each SKILL should be displayed to the user follows the [SKILL call display guide](templates\u002Flocales\u002Fen\u002Fmydocs\u002Fmanual\u002Ftask_workflow_guide.md). PR body structure and verification follow the [internal task PR guide](templates\u002Flocales\u002Fen\u002Fmydocs\u002Fmanual\u002Finternal_pr_guide.md), and PR creation commands plus document link formats follow the [PR command and link guide](templates\u002Flocales\u002Fen\u002Fmydocs\u002Fmanual\u002Fpr_command_guide.md).\n\nDocument structure and manual-document neutrality are checked in the [document structure manual](templates\u002Flocales\u002Fen\u002Fmydocs\u002Fmanual\u002Fdocument_structure_guide.md), not through a separate SKILL.\n\n### Task Cycle\n\nIf an Issue already exists, skip `task-register` and go directly to `task-start` to write the task plan. For example, when the task requester says `\"work on issue #17\"`, AI checks milestone and issue body for #17, then creates `local\u002Ftask17`, today's todo, and the task plan. Only when no Issue exists does `task-register` check duplicate Issues, milestone, and labels, ask for approval before creation, then create the GitHub Issue.\n\nEvery stage transition requires explicit approval from the task requester.\n\n```text\n0. Task registration -> `task-register`\n   └─ AI: check duplicate issues, milestone, and label candidates\n   └─ task requester: approve Issue creation\n   └─ AI: create GitHub Issue and request approval to enter `task-start`\n\n1. Task plan -> `task-start`\n   └─ task requester: specify an existing Issue such as \"work on issue #N\", or approve starting from the newly created Issue\n   └─ AI: write plan (minimum 3 stages, maximum 6 stages)\n   └─ task requester: review -> approve or request edits\n\n2. Stage implementation -> `task-stage-report` (repeat for each Stage)\n   └─ AI: write code + run tests\n   └─ AI: write Stage completion report\n   └─ task requester: verify -> approve or give feedback\n\n3. Feedback application -> (manual)\n   └─ task requester: write feedback document (mydocs\u002Ffeedback\u002F), then AI applies it. If scope changes, update the plan and receive re-approval\n   └─ AI: apply feedback and revise\n\n4. Final report + Open PR -> `task-final-report`\n   └─ AI: write final result report and create an Open PR with structured verification evidence\n   └─ task requester: verify -> approve or give feedback\n\n5. PR review + merge + cleanup -> `pr-merge-cleanup`\n   └─ task requester: review PR -> approve or give feedback\n   └─ AI: after review and merge, close Issue and clean branches\u002Ftoday's todo\n```\n\n`todo` is called whenever the today's todo board is updated in the above flow. `external-pr-review` is a separate flow for reviewing external contributor PRs.\n\n### Document Structure\n\nDocuments used or produced by tasks:\n\n```text\nmydocs\u002F\n├── _templates\u002F                         \u003C- output formats by artifact type\n├── orders\u002Fyyyymmdd.md                  \u003C- today's todo (task list + status)\n├── plans\u002Ftask_{milestone}_{N}.md       \u003C- task plan\n├── plans\u002Ftask_{milestone}_{N}_impl.md  \u003C- implementation plan\n├── working\u002Ftask_{milestone}_{N}_stage{S}.md\n│                                        \u003C- Stage completion report\n├── report\u002Ftask_{milestone}_{N}_report.md\n│                                        \u003C- final result report\n├── feedback\u002F                           \u003C- feedback and review notes\n├── tech\u002F                               \u003C- technical research and pre-official drafts\n├── manual\u002F                             \u003C- operating manuals and repeated work standards\n├── troubleshootings\u002F                   \u003C- troubleshooting\n└── pr\u002F                                 \u003C- external PR review records\n```\n\nFolder roles, document filename rules, and artifact output formats are defined in the [document structure manual](templates\u002Flocales\u002Fen\u002Fmydocs\u002Fmanual\u002Fdocument_structure_guide.md). Each folder's detailed writing rules are checked from that folder's `README.md`.\n\n| Area | Policy |\n|---|---|\n| `mydocs\u002F` | Stores work memory, operating manuals, and research evidence. It is not the official product documentation root of the target project. |\n| Official product docs | Hyper-Waterfall does not fix the official documentation root name. A target project may choose `docs\u002F`, `specs\u002F`, `site\u002F`, `website\u002F`, `adr\u002F`, GitHub Wiki, or another path. Tasks that create, move, or edit product\u002Fuser\u002Fcontributor\u002FAPI\u002Farchitecture\u002Froadmap docs must first get approval in the task plan's document location decision, including target audience, officialization level, selected path, alternative path, and reason. |\n| `manual\u002F` | Contains recurring operating standards and procedures. Records for a specific Issue, PR, release verification, or incident are separated into the corresponding artifact document. Details follow the [manual document neutrality policy](templates\u002Flocales\u002Fen\u002Fmydocs\u002Fmanual\u002Fdocument_structure_guide.md). |\n| `tech\u002F` | Contains technical research, alternative comparisons, design rationale, and drafts that are not yet official. To promote them into official contract docs for users or external integrators, open a separate task, choose the official docs root, and receive approval. |\n| `_templates\u002F` | The source of truth for output formats, not an actual task artifact folder. Each Skill reads the corresponding template in `mydocs\u002F_templates\u002F` first and uses the minimal section summary inside the Skill only as fallback when the template cannot be read. |\n| GitHub Issue and Pull Request | GitHub platform artifacts. Issue bodies follow `.github\u002FISSUE_TEMPLATE\u002Ftask.yml`, PR bodies follow `.github\u002Fpull_request_template.md`, and repository-resident work documents follow `mydocs\u002F_templates\u002F`. Details follow the [GitHub platform template policy](templates\u002Flocales\u002Fen\u002Fmydocs\u002Fmanual\u002Fdocument_structure_guide.md). |\n\n## Target Repository Structure After Adoption\n\nAfter `templates\u002F` is copied and placeholders are replaced, the target repository looks like this.\n\n```text\nyour-repo\u002F\n├── AGENTS.md                       single source of truth for operating rules\n├── CLAUDE.md                       for Claude Code (references AGENTS.md)\n├── .hyper-waterfall\u002F\n│   └── version.json                 records the applied Hyper-Waterfall version and locale\n├── .github\u002F\n│   ├── ISSUE_TEMPLATE\u002F\n│   │   └── task.yml\n│   └── pull_request_template.md\n├── .agents\u002F\n│   └── skills -> ..\u002Fmydocs\u002Fskills  Codex recognition path (symlink)\n├── .claude\u002F\n│   └── skills -> ..\u002Fmydocs\u002Fskills  Claude Code recognition path (symlink)\n└── mydocs\u002F\n    ├── _templates\u002F         output format templates by artifact type\n    ├── manual\u002F             operating manuals (document structure, task workflow, Git, PR, lifecycle, release\u002Fupdate, conflict rules)\n    ├── skills\u002F             SKILL source of truth (shared by Codex\u002FClaude Code)\n    ├── orders\u002F             today's todo (yyyymmdd.md)\n    ├── plans\u002F              task and implementation plans\n    │   └── archives\u002F\n    ├── working\u002F            Stage completion reports\n    ├── report\u002F             final result reports\n    ├── feedback\u002F           feedback and review notes\n    ├── tech\u002F               technical research and pre-official drafts\n    ├── troubleshootings\u002F   troubleshooting\n    └── pr\u002F                 external PR review records\n        └── archives\u002F\n```\n\n| Area | What It Provides |\n|---|---|\n| `AGENTS.md`, `CLAUDE.md` | Loads common operating rules into AI coding agents. `AGENTS.md` is the source of truth, and `CLAUDE.md` delegates to it. |\n| `.hyper-waterfall\u002Fversion.json` | Records the applied framework version and selected locale, then supports update judgment. |\n| `.github\u002F` | Fixes the GitHub Issue Form and Pull Request body structure. |\n| `.agents\u002Fskills`, `.claude\u002Fskills` | Lets Codex and Claude Code read the same SKILL text through symlinks. |\n| `mydocs\u002F_templates\u002F` | Fixes output formats for plans, reports, feedback, technical research, troubleshooting, and external PR reviews. |\n| `mydocs\u002Fmanual\u002F` | Contains repeated operating policies and procedures. |\n| `mydocs\u002Forders\u002F`, `plans\u002F`, `working\u002F`, `report\u002F` | Stores daily task state, plans, Stage reports, and final reports. |\n| `mydocs\u002Ffeedback\u002F`, `tech\u002F`, `troubleshootings\u002F`, `pr\u002F` | Stores feedback, research, troubleshooting, and external PR review records. |\n\nThe symlink structure for `.agents\u002Fskills` and `.claude\u002Fskills` in the adopted repository follows the [Agent Skills location policy](templates\u002Flocales\u002Fen\u002Fmydocs\u002Fmanual\u002Fdocument_structure_guide.md). `.hyper-waterfall\u002Fversion.json` and manifest-based update flow are documented in the [distribution manifest and version record policy](templates\u002Flocales\u002Fen\u002Fmydocs\u002Fmanual\u002Fdocument_structure_guide.md), [`docs\u002Flifecycle\u002Fupdate.en.md`](docs\u002Flifecycle\u002Fupdate.en.md), and [`docs\u002Flifecycle\u002Fupdate_pr.en.md`](docs\u002Flifecycle\u002Fupdate_pr.en.md).\n\nThe framework's document templates, GitHub Issue Form, and SKILL source of truth are `templates\u002Fmydocs\u002F_templates\u002F`, `templates\u002F.github\u002FISSUE_TEMPLATE\u002Ftask.yml`, and `templates\u002Fmydocs\u002Fskills\u002F`. In an adopted repository, `.agents\u002Fskills` and `.claude\u002Fskills` symlinks point to the same `mydocs\u002Fskills` text.\n\n## Maintainer Details\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Updating Existing Adopted Repositories\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nExisting adopted repositories are updated based on GitHub Releases\u002Ftags and the manifest. AI uses [`docs\u002Fagent-entrypoint.en.md`](docs\u002Fagent-entrypoint.en.md) as the entry point and follows the existing-update judgment format in [`docs\u002Flifecycle\u002Fupdate.en.md`](docs\u002Flifecycle\u002Fupdate.en.md), first reporting current version, current locale, requested locale or switch request, target release\u002Ftag, target release locale support, migration guide, manifest diff, locale manifest diff, and Hyper-Waterfall version update PR candidates.\n\nWhen converting approved update candidates into a PR, follow [`docs\u002Flifecycle\u002Fupdate_pr.en.md`](docs\u002Flifecycle\u002Fupdate_pr.en.md). The npm CLI is a convenience execution channel for the same judgment and does not replace the canonical basis: GitHub Release\u002Ftag, `templates\u002Fmanifest.json`, and migration guide. CLI output alone does not automatically apply files; only approved scope is converted into the normal task flow.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>CLI and Distribution Channels\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nThe `hyper-waterfall` CLI is distributed through npm and can run lifecycle judgment through version-pinned `npx` commands. The `v0.3.0` release status and post-publish verification results are tracked in [`docs\u002Freleases\u002Fv0.3.0.md`](docs\u002Freleases\u002Fv0.3.0.md).\n\n```bash\nnpx hyper-waterfall@0.3.0 init --repo . --dry-run\nnpx hyper-waterfall@0.3.0 update --repo . --from v0.2.0 --to v0.3.0 --dry-run\nnpx hyper-waterfall@0.3.0 doctor --repo .\n```\n\nOn macOS, you can install the CLI through the public Homebrew tap.\n\n```bash\nbrew install postmelee\u002Ftap\u002Fhyper-waterfall\nhyper-waterfall --version\nhyper-waterfall doctor --repo .\n```\n\nAdditional distribution channels such as Homebrew, Docker, Codex plugin, and Claude plugin are treated only as protocol execution channels that do not replace the canonical basis. Channel purpose, non-goals, operating cost, and priority are summarized in [`docs\u002Fdistribution-channels.md`](docs\u002Fdistribution-channels.md).\n\nThis Homebrew formula is a wrapper that installs the npm CLI and does not replace the canonical basis: GitHub Release\u002Ftag, `templates\u002Fmanifest.json`, and migration guide. Homebrew may install the Node runtime as a dependency. The path `brew install hyper-waterfall` without specifying a tap requires inclusion in Homebrew core, but as of the review criteria in [#46](https:\u002F\u002Fgithub.com\u002Fpostmelee\u002Fhyper-waterfall\u002Fissues\u002F46), this repository keeps the public tap path and does not submit to core.\n\n\u003C\u002Fdetails>\n\n---\n\n## Appendix\n\n**Part 1. The Original Hyper-Waterfall** ([rhwp](https:\u002F\u002Fgithub.com\u002Fedwardkim\u002Frhwp))\n\n1. [What Is Hyper-Waterfall?](#what-is-hyper-waterfall)\n2. [Core Structure](#core-structure)\n3. [Core Principles](#core-principles)\n4. [Role Split](#role-split)\n5. [Vibe Coding vs Hyper-Waterfall](#vibe-coding-vs-hyper-waterfall)\n6. [Why It Is Powerful — The Point AI Makes Reachable](#why-it-is-powerful--the-point-ai-makes-reachable)\n\n**Part 2. postmelee\u002Fhyper-waterfall**\n\n1. [postmelee\u002Fhyper-waterfall: Turning the Methodology into a Harness](#postmeleehyper-waterfall-turning-the-methodology-into-a-harness)\n2. [Live Example — Follow It Yourself](#live-example--follow-it-yourself)\n3. [Design Principles](#design-principles)\n4. [Prompt Guide Alignment](#prompt-guide-alignment)\n5. [License](#license)\n\n---\n\n## What Is Hyper-Waterfall?\n\n### Macro Waterfall + Micro Agile: AI Makes Both Possible at the Same Time\n\nA methodology that was impossible before AI: waterfall's discipline and agile's speed at once.\n\n> This methodology was refined from real project experience such as [`edwardkim\u002Frhwp`](https:\u002F\u002Fgithub.com\u002Fedwardkim\u002Frhwp) and [`postmelee\u002Falhangeul-macos`](https:\u002F\u002Fgithub.com\u002Fpostmelee\u002Falhangeul-macos).\n> Its core philosophy is captured most completely in [edwardkim\u002Frhwp · hyper_waterfall.md](https:\u002F\u002Fgithub.com\u002Fedwardkim\u002Frhwp\u002Fblob\u002Fmain\u002Fmydocs\u002Fmanual\u002Fhyper_waterfall.md). This repository modularizes that methodology so it can be applied easily to other repositories.\n\nTo understand the methodology first, start with [Core Structure](#core-structure). To see what this repository adds, jump to [postmelee\u002Fhyper-waterfall: Turning the Methodology into a Harness](#postmeleehyper-waterfall-turning-the-methodology-into-a-harness).\n\n## Core Structure\n\n### Macro Waterfall + Micro Agile\n\n```text\nMacro (project level) — waterfall discipline:\n  Plan ──→ Design ──→ Implement ──→ Verify ──→ Release\n   │        │          │             │          │\n   ▼        ▼          ▼             ▼          ▼\n  Docs     Docs       Docs          Docs       Docs\n\nMicro (task level, hours) — agile speed:\n  Implement ──→ Test ──→ Feedback ──→ Revise ──→ Test → ... (fast iteration)\n      │          │          │           │          │\n      AI      automation  human judgment AI      automation\n```\n\n- Macro direction is controlled by **waterfall discipline**: plans, approvals, staged reporting, and final verification.\n- Micro execution uses **agile fast iteration**: AI and immediate feedback loops, with the full cycle completing within **hours**.\n\nEvery task is documented, and every decision is recorded. This is what makes Hyper-Waterfall possible.\n\n## Core Principles\n\n> **Humans never stop thinking.**\n\nNo matter how capable AI becomes, humans decide the direction and judge quality. The moment you accept AI output without reading it, Hyper-Waterfall collapses into vibe coding. Operationally, this principle becomes three rules.\n\n### 1. Humans Keep Direction Until the End\n\nStage transitions, plan changes, and source edits require explicit approval from the task requester. AI is a tool for decisions, not the decision maker. Once gates are skipped even once, the methodology breaks down quickly.\n\n### 2. Always Give AI Enough Context\n\nIntent and plans are embedded in `mydocs\u002F` so the task's intent, scope, and approval criteria do not need to be explained from scratch in every prompt. Models read the same repository and work on the same context. If work starts with scattered context, AI fills the gaps by guessing.\n\n### 3. Periodically Externalize AI Work Memory\n\nStage reports, final reports, and PR bodies distill and record intent, decisions, and verification evidence. Chat context disappears, but repository markdown remains. New sessions and new contributors can start from the same baseline.\n\n## Role Split\n\n### Task Requester (Human)\n\nThe human focuses on **thinking**:\n\n- Direction: \"What should we do next?\"\n- Priority: \"What matters more?\"\n- Quality judgment: \"Is this good enough?\"\n- Architecture decision: \"Is this structure correct?\"\n- Domain knowledge: \"How should this behave in this domain?\"\n- Feedback: \"This part is wrong, because...\"\n\n### AI Pair Programmer\n\nAI focuses on **execution**:\n\n- Analysis: codebase exploration, root-cause tracing\n- Planning: implementation plan drafting\n- Implementation: code writing, test generation\n- Documentation: reports, technical docs, commit messages\n- Debugging: log analysis, fix proposals\n- Iteration: applying feedback and retrying\n\n## Vibe Coding vs Hyper-Waterfall\n\n> Vibe coding — `accepting AI output without reading it, letting AI make architecture decisions, and shipping code you do not understand` — is a trap. It may appear to work, but because you do not understand the result, you cannot diagnose problems when they happen.\n>\n> This project takes the opposite approach. The human task requester keeps complete ownership of direction, quality, and architecture decisions, while AI performs implementation at a speed and scale humans cannot reach alone. Key difference: **humans never stop thinking.**\n>\n> — [edwardkim\u002Frhwp · Vibe Coding vs AI-Driven Development](https:\u002F\u002Fgithub.com\u002Fedwardkim\u002Frhwp#%EB%B0%94%EC%9D%B4%EB%B8%8C-%EC%BD%94%EB%94%A9-vs-ai-%EC%A3%BC%EB%8F%84-%EA%B0%9C%EB%B0%9C)\n\n| | Vibe Coding | Hyper-Waterfall |\n|---|---|---|\n| **Human role** | Accept AI output | Direct, review, decide |\n| **Plan** | None — \"just build it\" | Task plan -> approval -> implementation plan -> Stage execution |\n| **Quality gates** | Hope it works | Verification at every Stage + approval gates + Open PR review |\n| **Debugging** | Ask AI to fix AI's bug | Human diagnoses, AI implements |\n| **Architecture** | Accidentally formed | Intentionally designed by the task requester |\n| **Docs** | None | `mydocs\u002F` (plans, Stage reports, final report) + Issue\u002FPR body |\n| Reproducibility | Impossible | Full process timeline is traceable |\n| **Result** | Fragile and hard to maintain | Traceable, handoff-ready, resumable anywhere |\n\n## Why It Is Powerful — The Point AI Makes Reachable\n\nMacro waterfall and micro agile were long treated as a trade-off. Discipline made things slow; speed removed discipline. AI pair programmers break this trade-off for the first time.\n\n### 1. Recover Discipline Without Losing Speed\n\nOne major reason waterfall became heavy was that **humans had to carry all documents, plans, and verification themselves**. AI can draft these quickly, letting us recover the speed waterfall lost and the discipline agile lost. **The same discipline, 100x faster** — this is the point that was unreachable without AI.\n\n### 2. Knowledge Is Externalized into the Repository, Not Kept in Heads\n\nDecisions, rationale, and verification results remain in `mydocs\u002F`, PRs, and Issues. Even if context concentrated in one person disappears, the next person or next AI session starts from **the same baseline**. Agile's bus-factor problem is structurally reduced.\n\n### 3. Humans Focus on Decisions, AI on Execution\n\nHumans remain responsible for direction, priority, architecture, and quality, while AI handles exploration, implementation, tests, documents, and repetition. A workload that one person's attention could not reach fits into one cycle. **AI is a multiplier**. Put it on top of a good process, and it produces exceptional results.\n\n### 4. Work Can Move Across Places\n\nThe maintainer of [rhwp](https:\u002F\u002Fgithub.com\u002Fedwardkim\u002Frhwp) works from the office, home, and while moving, using different Claude sessions in each place. Each new session has no memory of the previous one.\n\nBut documents answer the context questions:\n\n| Question | Answer |\n|---|---|\n| \"What should I do now?\" | `orders\u002F20260409.md` |\n| \"Where did we stop?\" | `working\u002Ftask_m100_86_stage1.md` |\n| \"What did we decide to do?\" | `plans\u002Ftask_m100_86_impl.md` |\n| \"Why this approach?\" | `feedback\u002F` + `tech\u002F` |\n| \"What is the trap here?\" | `troubleshootings\u002F` |\n\n**The task requester spends almost zero time transferring context.** This is why continuous work is possible across three places, and why the same structure works when contributors join.\n\n---\n\n## postmelee\u002Fhyper-waterfall: Turning the Methodology into a Harness\n\n> This repository references the Hyper-Waterfall methodology first introduced in [rhwp](https:\u002F\u002Fgithub.com\u002Fedwardkim\u002Frhwp) and extends it as follows.\n\n### 1. Apply It to Any Repository with One Prompt — Modularization + Placeholder Substitution\n\nThe original methodology in rhwp is tightly coupled to that repository's documents and conventions, so it is hard to copy directly into other projects. This repository separates operating rules, manuals, and SKILLs into `templates\u002F` and formalizes the entry procedure in [`docs\u002Fagent-entrypoint.en.md`](docs\u002Fagent-entrypoint.en.md). As a result, **one prompt to an AI coding tool** can apply it to any repository. The AI follows the entry procedure and automatically substitutes placeholders such as `REPO_SLUG` and `BASE_BRANCH`.\n\nLifecycle criteria for updating existing adopted repositories are also documented separately. GitHub Release\u002Ftag, manifest, migration guide, and `.hyper-waterfall\u002Fversion.json` are used to determine the current version, current locale, requested locale or switch request, target release\u002Ftag, target release locale support, manifest diff, locale manifest diff, and Hyper-Waterfall version update PR candidates first. Detailed criteria live in [`docs\u002Flifecycle\u002Fupdate.en.md`](docs\u002Flifecycle\u002Fupdate.en.md) and [`docs\u002Flifecycle\u002Fupdate_pr.en.md`](docs\u002Flifecycle\u002Fupdate_pr.en.md). This repository itself is the first dogfooding case applying Hyper-Waterfall to itself (Issue #1, PR #2).\n\n### 2. Alignment with Official Prompting Guides\n\nThe work document formats are designed to naturally satisfy the core of the official prompting guides from [OpenAI](https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fprompt-guidance) and [Anthropic](https:\u002F\u002Fplatform.claude.com\u002Fdocs\u002Fen\u002Fbuild-with-claude\u002Fprompt-engineering\u002Fclaude-prompting-best-practices). In particular, GitHub Issue\u002FPR templates structure GitHub platform artifacts, while `templates\u002Fmydocs\u002F_templates\u002F` specifies output formats for plans, reports, feedback, and external PR review documents.\n\n> This minimizes response quality degradation in the recursive process where AI writes documents, then reads and uses them again as references.\n\n- Clarity: task goals are clearly defined.\n- Consistency: all work documents share the same structure.\n- Step-by-step thinking: work is split into smaller stages.\n- Context: all information needed for work is included in documents.\n- Output format: task results are emitted in specific central template formats.\n\nSee the detailed mapping in [Prompt Guide Alignment](#prompt-guide-alignment).\n\n### 3. Multi-Agent Compatibility + Token and Context Efficiency Through Separated Rules, SKILLs, and Manuals\n\nrhwp inlined operating rules, document structure, folder policy, naming rules, and PR handling into a single `CLAUDE.md` file, and did not include `AGENTS.md`, so it operated as Claude Code-specific. This repository separates and expands it along two axes.\n\n**(1) Multi-agent compatibility**: `AGENTS.md` is the single source of truth, while `CLAUDE.md` references it with one `@AGENTS.md` line. SKILLs are recognized by both tools through `.agents\u002Fskills` (Codex) and `.claude\u002Fskills` (Claude Code) symlinks pointing to the same text. New tools that recognize SKILLs can extend the same pattern.\n\n**(2) Separation of operating rules, SKILLs, manuals, and templates**: `AGENTS.md` keeps only the policies, constraints, and index that must be loaded into every-turn system prompts. Procedural details are split into topic manuals under [`mydocs\u002Fmanual\u002F`](templates\u002Flocales\u002Fen\u002Fmydocs\u002Fmanual\u002F) (document structure, task workflow, Git, PR, lifecycle, release\u002Fupdate, conflict rules), each `mydocs\u002F` folder's `README.md`, GitHub Issue\u002FPR templates under [`.github\u002F`](templates\u002Flocales\u002Fen\u002F.github\u002F), document output formats under [`mydocs\u002F_templates\u002F`](templates\u002Flocales\u002Fen\u002Fmydocs\u002F_templates\u002F), and 7 SKILLs under [`mydocs\u002Fskills\u002F`](templates\u002Flocales\u002Fen\u002Fmydocs\u002Fskills\u002F).\n\nEffects:\n\n- **Token efficiency**: reduces content loaded into every-turn system prompts. Manuals and SKILL text enter context only when called.\n- **Context efficiency**: the model reads only the procedure needed at the current moment. Unrelated procedures do not pollute context.\n- **Clearer intent transfer**: GitHub templates and central templates fix the structure of repeated artifacts, and staged SKILLs state when they are called, so AI does not infer or reinvent procedure and output formats.\n- **Model portability**: SKILLs use a standard format and can be moved to other SKILL-aware tools.\n\n## Live Example — Follow It Yourself\n\nThis repository is the first case of Hyper-Waterfall applying itself to itself. If you want to see actual operation before deciding whether to adopt it, review these artifacts in order.\n\n1. **Issue** [`#1` Hyper-Waterfall self-adoption (dogfooding)](https:\u002F\u002Fgithub.com\u002Fpostmelee\u002Fhyper-waterfall\u002Fissues\u002F1) — a clean structure with 3 labels, milestone M010, and automatically linked PR (no status-noise comments)\n2. **Pull Request** [`#2`](https:\u002F\u002Fgithub.com\u002Fpostmelee\u002Fhyper-waterfall\u002Fpull\u002F2) — Open PR body format: 4 summary bullets (target task\u002Fwhy\u002Fwhat\u002Freview points), Stage timeline with dual links (Stage report + commit URL), impact table, work documents, verification results and evidence\n3. **Task plan** [`mydocs\u002Fplans\u002Ftask_m010_1.md`](mydocs\u002Fplans\u002Ftask_m010_1.md) — purpose, background, scope, design direction, expected changed files, tentative stages, verification plan, risks\n4. **5-stage implementation plan** [`mydocs\u002Fplans\u002Ftask_m010_1_impl.md`](mydocs\u002Fplans\u002Ftask_m010_1_impl.md) — stage artifacts, verification commands, and commit messages fixed in advance\n5. **5 Stage reports** [`mydocs\u002Fworking\u002F`](mydocs\u002Fworking\u002F) — artifacts, verification results, residual risks, and next-stage impact at each Stage boundary\n6. **Final report** [`mydocs\u002Freport\u002Ftask_m010_1_report.md`](mydocs\u002Freport\u002Ftask_m010_1_report.md) — 5-stage synthesis, before\u002Fafter quantitative comparison, acceptance criteria verification\n7. **Today's todo** [`mydocs\u002Forders\u002F`](mydocs\u002Forders\u002F) — daily board format (milestone tables + completion time)\n8. **Commit log** [`git log` (main)](https:\u002F\u002Fgithub.com\u002Fpostmelee\u002Fhyper-waterfall\u002Fcommits\u002Fmain) — 12 task commits preserved in chronological order from `Task #1: 수행 계획서 작성` through `pr-merge-cleanup`\n\nThis first task expanded scope twice and proceeded through 5 Stages. In other words, the README procedure is visible as live artifacts: approval gates, Stage reports, scope-change handling, PR body rewrite, and cleanup after merge.\n\n## Design Principles\n\n- Meaningful source changes require a human approval gate.\n- Issue progress tracking is delegated to GitHub linked PR auto-cross-references plus labels and milestones; comments are reserved for discussion, blockers, and decision records.\n- The latest state must be discoverable from Issue metadata, the current branch or PR, and `mydocs\u002F`.\n- This framework must work across many project types. Project-specific language, build, deployment, and product rules belong in the target repository's templates and settings, not in core.\n- Be strict about process and flexible about tools.\n\n> Hyper-Waterfall is not new magic. It is an operating method that restores waterfall discipline and agile speed at the same time on top of AI as a multiplier. On top of a good process, AI can produce exceptional results.\n\n## Prompt Guide Alignment\n\nHyper-Waterfall implements the core of the official OpenAI and Anthropic prompting guides at the development-process level. It is not about \"writing a good prompt\"; it is about building a **repository structure where prompts are structurally likely to be good**.\n\n### Alignment Summary\n\n| Principle | How Hyper-Waterfall Implements It | Effect |\n|---|---|---|\n| Clear goal | GitHub Issue, task plan, implementation plan | AI understands scope and success criteria first. |\n| Sufficient context | Plans, reports, feedback, and technical research in `mydocs\u002F` | New sessions restore context from repository documents. |\n| Output format constraints | `mydocs\u002F_templates\u002F`, Issue\u002FPR templates | Plans, reports, and verification results keep the same structure every time. |\n| Stepwise progress | Stage-level implementation, verification, and reporting | Complex work is split into reviewable units. |\n| Verification criteria | Stage reports, final report, PR body | Results are judged by recorded criteria, not feeling. |\n| Stop conditions | Approval gates | AI does not advance to the next step arbitrarily. |\n| Long-term work memory | `mydocs\u002F`, commit log, PR timeline | Work history remains even when chat disappears. |\n| Lightweight context | `1 Issue = 1 Task = 1 Branch = 1 Session` | Sessions stay small and clear. |\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>OpenAI prompt guidance mapping\u003C\u002Fstrong> · source: \u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fprompt-guidance\">OpenAI prompt guidance\u003C\u002Fa>\u003C\u002Fsummary>\n\n1. **Define the output first.**\n   Hyper-Waterfall defines artifacts from the start: Issue, task plan, implementation plan, Stage report, final report, and PR. Instead of asking AI to \"do a good job,\" it first fixes what must be left behind.\n\n2. **Describe what a good answer means.**\n   Each Stage records not only implementation but also verification criteria and review points. AI output is judged against documented criteria, not intuition.\n\n3. **Set short constraints.**\n   Hyper-Waterfall makes boundaries explicit: \"do not proceed to the next Stage without approval,\" \"ask before source edits,\" and \"track by Issue.\" This does not remove freedom; it lays rails that prevent runaway execution.\n\n4. **State the level of evidence needed.**\n   Implementation results are distilled into Stage reports, verification logs, and PR bodies. The repository keeps not only what changed, but why it changed and how it was checked.\n\n5. **Specify the output format.**\n   `mydocs\u002F_templates\u002F` fixes the expected output shape for task plans, implementation plans, Stage reports, final reports, feedback, technical research, troubleshooting, and external PR review documents. `.github\u002Fpull_request_template.md` structures PR bodies for the review screen. AI answers are shaped into artifacts the next worker can read again.\n\n6. **Tell the model when to stop.**\n   Hyper-Waterfall stops at every Stage boundary and waits for human approval. AI does not run to the end; it stops at lines where humans can confirm direction.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Anthropic Claude prompting best practices mapping\u003C\u002Fstrong> · source: \u003Ca href=\"https:\u002F\u002Fplatform.claude.com\u002Fdocs\u002Fen\u002Fbuild-with-claude\u002Fprompt-engineering\u002Fclaude-prompting-best-practices\">Claude prompting best practices\u003C\u002Fa>\u003C\u002Fsummary>\n\n1. **Clear and direct instructions.**\n   Task intent is made explicit at every step through the Issue, task plan, and implementation plan. Instead of giving the model ambiguous intent, the method fixes what to build, why, and how far before the gate.\n\n2. **Workflow and goal context.**\n   Users do not need to include in every prompt how the work fits into the larger flow or artifact. That context is embedded in `mydocs\u002F`, Issues, and PR bodies, so the model naturally reads the same context.\n\n3. **Sequential steps.**\n   Stage-based progress and approval gates directly implement the practice of splitting instructions into sequential steps.\n\n4. **Output format control.**\n   Task plans, Stage reports, final reports, feedback, technical research, and external PR review documents follow the desired output format in `mydocs\u002F_templates\u002F`, while PR bodies follow `.github\u002Fpull_request_template.md`. The model does not invent where to write what on each task.\n\n5. **Long-running work and external memory.**\n   `mydocs\u002F` directly supports long-horizon agentic work and memory tasks. Even if chat context disappears, work memory is distilled into the filesystem.\n\n6. **Literal instruction following and alignment.**\n   More literal models tend to bind more tightly to explicit scope. Hyper-Waterfall documents boundaries such as \"ask before source edits,\" \"do not proceed to the next Stage without approval,\" and \"track by Issue,\" so literal instruction following works in favor of the process.\n\n> Hyper-Waterfall prioritizes human control and traceability over maximum autonomy. It does not operate at the same layer as guidance for one-turn interactive coding; it adds a higher-level task gate across the whole task. XML tag structuring is not adopted directly; `mydocs\u002F` folder structure, filename rules, and central templates perform the same role.\n\n> **One-line summary**: Hyper-Waterfall implements the core of Claude prompting best practices as a development-process harness, not as a single prompt sentence.\n\n\u003C\u002Fdetails>\n\n## License\n\nMIT. See [LICENSE](LICENSE) for details.\n","Hyper-Waterfall 是一种可追溯、审批驱动的方法论框架，用于将AI配对编程转变为可控的开发流程。其核心功能在于通过人类决策主导、审批门限、外部化工作记忆、分阶段执行以及可恢复过程等机制，确保AI在快速实现代码的同时，保持开发过程的透明性和可审查性。技术上采用JavaScript实现，并通过Issue、分支、计划、阶段报告、最终报告和PR等环节构建起一个完整的开发循环。该项目特别适用于需要结合AI高效编码能力和人类智慧指导的软件开发场景，尤其当团队希望利用AI加速开发同时又不失去对项目方向控制时。",2,"2026-06-11 04:03:33","CREATED_QUERY"]