commitgate 0.1.1 โ†’ 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.en.md +120 -244
  2. package/README.md +121 -245
  3. package/package.json +1 -1
package/README.en.md CHANGED
@@ -1,341 +1,217 @@
1
- # CommitGate ๐Ÿšฆ
1
+ # CommitGate
2
2
 
3
3
  ๐ŸŒ [ํ•œ๊ตญ์–ด](./README.md) ยท **English**
4
4
 
5
- **A "commit gate" that lets AI-written code be committed only after a *different* AI reviews and approves it.**
5
+ **A commit gate that blocks AI-generated code from being committed until Codex has reviewed and approved it.**
6
6
 
7
- > In one line: pair a **Builder AI** with a **Reviewer AI** so that **nothing gets committed without review, approval, and evidence.**
7
+ AI coding agents can move quickly, but unreviewed changes should not go straight into your history. CommitGate wraps each change in a REQ ticket and only allows the staged tree approved by Codex to be committed. If the code changes after approval, or if evidence is missing, it fails closed.
8
8
 
9
9
  [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
10
10
 
11
11
  ---
12
12
 
13
- ## ๐Ÿค” What is this? (an analogy)
13
+ ## Quick Start
14
14
 
15
- Think of an airport security checkpoint. No matter how much of a hurry you're in, you **can't reach the gate without passing through security.**
15
+ Run this from your project root. The project must be a **git repository with a `package.json`**.
16
16
 
17
- CommitGate works the same way. No matter how much code you produce, **`git commit` is blocked until it passes the "review โ†’ approval" gate.**
18
-
19
- - ๐Ÿ› ๏ธ **Builder (the maker)** โ€” you, or your AI coding tool (e.g. Claude Code). Designs the requirement and writes the code.
20
- - ๐Ÿ”Ž **Reviewer (the checker)** โ€” the **Codex CLI**. **Independently re-reviews** what the Builder made and rules pass / needs-fix.
21
- - ๐Ÿšฆ **CommitGate** โ€” stands between them and lets **only Reviewer-approved code** be committed.
22
-
23
- In short, instead of "build alone, commit alone," it enforces **cross-verification between the AI that built it and the AI that checked it.**
24
-
25
- ## ๐ŸŽฏ What problem does it solve?
26
-
27
- AI produces code **fast**, but committing it without verification is risky. CommitGate:
28
-
29
- - โœ… Forces **every change through review.**
30
- - โœ… Binds approval to **"the exact code that was reviewed."** (You can't swap in changes after approval โ€” it's compared like a fingerprint.)
31
- - โœ… **Blocks by default (fail-closed)** whenever something is ambiguous or missing. "Pass only when certain" is the default, so it's safe.
32
- - โœ… Leaves **evidence on disk** of who approved what and when.
33
-
34
- ## ๐Ÿ”„ The flow at a glance
35
-
36
- ```
37
- โ‘  create ticket โ†’ โ‘ก write design โ†’ โ‘ข design review(Codex) โ†’ โ‘ฃ implement code
38
- req:new req:review-codex
39
-
40
- โ†’ โ‘ค gate check โ†’ โ‘ฅ code review(Codex) โ†’ โ‘ฆ commit once approved
41
- req:doctor req:review-codex req:commit
17
+ ```sh
18
+ npx commitgate
19
+ npm install
20
+ codex --version
21
+ codex login status
42
22
  ```
43
23
 
44
- At each step, **if it doesn't pass, you can't move to the next.**
45
-
46
- ---
47
-
48
- ## ๐Ÿ“ฆ Prerequisites
24
+ Then paste this prompt into your AI coding agent.
49
25
 
50
- You need these 4 things before starting. Check each in your terminal.
26
+ ```text
27
+ Do not handle this as a normal implementation. Use the CommitGate workflow installed in this project.
51
28
 
52
- | What | Check command | If missing |
53
- |---|---|---|
54
- | **Git** (required) | `git --version` | install from [git-scm.com](https://git-scm.com) |
55
- | **Node.js 18.17+** (required) | `node --version` | install from [nodejs.org](https://nodejs.org) |
56
- | **Codex CLI** (for review) | `codex --version` | install OpenAI Codex CLI (without it only review is unavailable; the rest works) |
57
- | **Package manager** | `npm --version` | `npm` ships with Node (or use `pnpm`/`yarn`) |
58
-
59
- > ๐Ÿ’ก **Reviewer = Codex CLI.** To actually run reviews, the Codex CLI must be installed. Without it, review commands **fail safely (fail-closed)** โ€” they never silently pass.
60
-
61
- ### ๐Ÿ”ง Install & log in to the Codex CLI (Reviewer setup)
29
+ Create a new REQ ticket and run this flow end to end:
30
+ req:new โ†’ write design docs โ†’ Codex design review โ†’ implement and test โ†’ req:doctor โ†’ Codex phase review โ†’ req:commit
62
31
 
63
- Reviews in CommitGate are handled by the **OpenAI Codex CLI**. Three steps:
32
+ Proceed automatically:
33
+ - If Codex returns NEEDS_FIX, fix the findings and rerun review until approved.
34
+ - The review target is only what has been staged with git add.
35
+ - Do not manually git add state.json or responses/.
64
36
 
65
- **โ‘  Install**
37
+ Stop for human confirmation only:
38
+ - Right before req:commit --run
39
+ - Before merging to main or pushing
40
+ - Before destructive actions such as reset, clean, or force push
41
+ - When the requested scope must change
42
+ - When Codex review is still not approved after 3 rounds
66
43
 
67
- ```sh
68
- # npm (all OSes)
69
- npm install -g @openai/codex
70
-
71
- # or macOS Homebrew
72
- brew install codex
44
+ Requirement:
45
+ - What:
46
+ - Why:
47
+ - Constraints:
48
+ - Done when:
73
49
  ```
74
50
 
75
- Verify:
51
+ The agent's first reply should look roughly like this.
76
52
 
77
- ```sh
78
- codex --version # e.g. codex-cli 0.4x.x
53
+ ```text
54
+ REQ-2026-002 created
55
+ Branch: feat/req-2026-002-profile-edit-api
56
+ Phases:
57
+ - phase-1: implement PATCH /profile
58
+ - phase-2: tests and regression checks
59
+ Control points: before req:commit --run, before push
79
60
  ```
80
61
 
81
- **โ‘ก Log in** โ€” pick whichever is easier
82
-
83
- - **Option A. With a ChatGPT account (recommended, browser)**
84
- ```sh
85
- codex login
86
- ```
87
- A browser opens โ†’ sign in with your ChatGPT account โ†’ return to the terminal when done.
62
+ After that, the agent runs design, implementation, tests, and Codex review. You only confirm at control points such as commit or push.
88
63
 
89
- - **Option B. With an OpenAI API key**
90
- ```sh
91
- # via environment variable (simplest)
92
- export OPENAI_API_KEY=sk-... # Windows PowerShell: $env:OPENAI_API_KEY="sk-..."
64
+ ---
93
65
 
94
- # or store the key in Codex
95
- printenv OPENAI_API_KEY | codex login --with-api-key
96
- ```
97
- Create an API key at [platform.openai.com](https://platform.openai.com/api-keys).
66
+ ## What Does It Enforce?
98
67
 
99
- **โ‘ข Verify login**
68
+ CommitGate is designed to block **unreviewed changes from being committed**, not just to wrap commands.
100
69
 
101
- ```sh
102
- codex login status # shows login status
103
- codex doctor # full diagnosis of install, auth, and environment (explains any issue)
104
- ```
70
+ - No Codex approval means no commit.
71
+ - If the approved staged tree differs from the current staged tree, the commit is blocked.
72
+ - Workflow files such as `state.json` and `responses/` cannot be mixed into the source commit.
73
+ - If Codex CLI is missing or fails, the workflow fails instead of silently passing.
74
+ - Approval responses and evidence are kept under `workflow/REQ-.../responses/`.
105
75
 
106
- > โœ… If `codex --version` and `codex login status` look good, the Reviewer is ready. Move on to `npx commitgate`.
107
- > โš ๏ธ If Windows can't find the `codex` command, open a **new terminal** so PATH is reloaded (a common issue right after a global install).
76
+ In short: **approved changes pass, ambiguous changes stop.**
108
77
 
109
78
  ---
110
79
 
111
- ## ๐Ÿš€ Install (one line)
112
-
113
- **In your project folder** (= a git repo that has a `package.json`):
80
+ ## What Installation Adds
114
81
 
115
- ```sh
116
- npx commitgate
117
- ```
82
+ `npx commitgate` adds the following to the target project. Existing files are not overwritten by default.
118
83
 
119
- What this does automatically (it **never overwrites** existing files):
120
-
121
- 1. Copies the workflow scripts (`scripts/req/`) and schemas.
122
- 2. Creates a `req.config.json` (settings file).
123
- 3. Adds the `req:*` commands and required devDependencies (`tsx`, `ajv`, `cross-spawn`) to your `package.json`.
124
- 4. Creates an `AGENTS.md` template (the rules file the Reviewer reads) if you don't have one.
84
+ | Added item | Purpose |
85
+ |---|---|
86
+ | `scripts/req/` | `req:new`, `req:review-codex`, `req:doctor`, `req:commit` scripts |
87
+ | `workflow/*.schema.json` | Schemas for Codex responses and config |
88
+ | `req.config.json` | Project-level configuration |
89
+ | `AGENTS.md` | Template rules for the agent and reviewer |
90
+ | `package.json` scripts | `req:*` commands and required devDependencies |
125
91
 
126
- After installing, fetch the newly added dependencies:
92
+ Preview without writing files:
127
93
 
128
94
  ```sh
129
- npm install
95
+ npx commitgate --dry-run
130
96
  ```
131
97
 
132
- > Add `--dry-run` to preview what it would do **without changing anything**: `npx commitgate --dry-run`
133
-
134
98
  ---
135
99
 
136
- ## ๐Ÿค– How to use it โ€” hand it to an AI agent via a prompt (recommended)
137
-
138
- Honestly, **nobody types `req:new โ†’ review โ†’ implement โ†’ review โ†’ commit` by hand, one at a time.** It's tedious.
139
-
140
- The real way to use CommitGate is this: **give your AI coding agent a prompt with your "requirements" plus "use this workflow," and the agent drives the whole thing.** You only approve at **control points (commit, merge, push, etc.).**
141
-
142
- ### What this mode assumes
143
- - **An AI coding agent that can run shell commands** โ€” Claude Code, Cursor (agent), Codex CLI, etc. (it must be able to run terminal commands in your repo)
144
- - **Codex CLI installed** โ€” the Reviewer role. Without it, the review step stops (fail-closed).
145
- - **A filled-in `AGENTS.md`** โ€” write your project's rules (coding conventions, test commands, etc.) into the template that `npx commitgate` created; it improves review quality.
146
-
147
- ### Three steps and you're done
148
- 1. Copy the **prompt template** below and fill the `[Requirements]` block at the bottom with your request.
149
- 2. Paste the whole thing **into your AI agent's chat.**
150
- 3. The agent's **first reply reports only the REQ number, branch, phase plan, and control points.** After that it asks you **only at control points** โ€” everything else (implementation, tests, Codex review, applying NEEDS_FIX, re-review) is automatic.
151
-
152
- ### ๐Ÿ“‹ Copy-paste prompt template
100
+ ## Prerequisites
153
101
 
154
- ````text
155
- Do NOT handle this as a normal implementation task. You MUST use the CommitGate (AI REQ workflow) installed in this project.
156
-
157
- Issue a new REQ ticket for the [Requirements] below and drive it all the way through:
158
- req:new โ†’ write design docs (00/01/02) โ†’ req:review-codex (design review)
159
- โ†’ implement phase + tests โ†’ req:doctor (gate) โ†’ req:review-codex (phase review) โ†’ req:commit
160
-
161
- [Do automatically]
162
- - Within the approved phase scope, do implementation, tests, keeping codex-request consistent, applying NEEDS_FIX, and re-review (resume) automatically. Do not ask me every time.
163
- - If Codex returns NEEDS_FIX, apply the feedback and re-run the review until approved (max 3 rounds per phase).
164
- - Only what is `git add`ed is reviewed. NEVER `git add` state.json or responses/ (the tool manages those).
165
-
166
- [Control points โ€” stop and ask me ONLY here]
167
- - Right before `req:commit --run` (the actual commit / HIGH impact)
168
- - Right before merging to main or `git push`
169
- - Destructive operations such as reset, clean, force push
170
- - When a design-scope change or a feature not in [Requirements] is needed
171
- - When Codex review exceeds 3 rounds without approval, or the judgment is unclear
172
- - When a prerequisite is missing (not a git repo, no Codex CLI / Node / package manager) and you must fail-closed
173
-
174
- [First reply] Report only the REQ number, branch, phase plan, and control points. After that, stop only at control points.
175
-
176
- [Requirements]
177
- - What: (e.g.) Add a user-profile edit API
178
- - Why: (e.g.) Only the name is editable today โ€” email and bio should be editable too
179
- - Constraints: (e.g.) Reuse the existing auth middleware, validate email format, no new external libraries
180
- - Done when: (e.g.) PATCH /profile works + unit tests pass + existing tests unbroken
181
- ````
182
-
183
- > The `[Requirements]` example above is **just a sample.** Just replace the 4 lines (What / Why / Constraints / Done when) with your own. If the request is large, it's split into multiple phases, each going through its own review and gate.
102
+ | Requirement | Check | Notes |
103
+ |---|---|---|
104
+ | Git | `git --version` | Required |
105
+ | Node.js 18.17+ | `node --version` | Required |
106
+ | npm, pnpm, or yarn | `npm --version` | Examples use npm |
107
+ | Codex CLI | `codex --version` | Required for review runs |
184
108
 
185
- ### Example of the agent's first reply
109
+ If Codex CLI is not installed:
186
110
 
187
- ```
188
- Issued REQ-2026-002 ยท branch feat/req-2026-002-profile-edit-api
189
- Phase plan:
190
- - phase-1: PATCH /profile handler + validation
191
- - phase-2: unit tests + regression
192
- Control points: proceed per phase after design approval / confirm before req:commit --run / push needs separate approval
193
- โ†’ Starting with the design docs. Once the design review passes, I'll move to implementation.
111
+ ```sh
112
+ npm install -g @openai/codex
113
+ codex login
114
+ codex login status
194
115
  ```
195
116
 
196
- Now you just **wait** until a control-point notification arrives. When it asks "commit as-is?" right before committing, you confirm.
117
+ On Windows, if `codex` is not found right after installation, open a new terminal so PATH is reloaded.
197
118
 
198
119
  ---
199
120
 
200
- ## ๐Ÿ”ง Appendix: what the workflow actually runs under the hood (manual steps)
121
+ ## Manual Commands
201
122
 
202
- > With the prompt approach above, you **don't need to type the commands below** โ€” the agent runs them for you.
203
- > These are the actual commands the workflow runs internally. Refer to them only when you need to **understand the behavior, debug, or run steps manually.**
204
-
205
- Let's walk the whole flow with one small feature as an example. (Commands use `npm`; arguments after `npm run` go after `--`. With `pnpm` you can drop the `--`, e.g. `pnpm req:new my-feature --run`.)
206
-
207
- ### Step 1 โ€” create a work ticket
123
+ Most users should use the prompt flow above. This section is for understanding what the workflow runs internally or for debugging.
208
124
 
209
125
  ```sh
126
+ # 1. Create a ticket and branch
210
127
  npm run req:new -- my-feature --run
211
- ```
212
-
213
- - A new branch (`feat/req-...`) is created, and three design docs appear under `workflow/REQ-2026-001/`.
214
- - The output shows a **ticket number** (e.g. `REQ-2026-001`). Later commands use just the number โ†’ `2026-001`
215
-
216
- ### Step 2 โ€” write the design docs
217
-
218
- Fill in the three files under `workflow/REQ-2026-001/`:
219
-
220
- - `00-requirement.md` โ€” **what** to build and why
221
- - `01-design.md` โ€” **how** to build it
222
- - `02-plan.md` โ€” in what **order/phases** to proceed
223
-
224
- ### Step 3 โ€” get a design review (Codex)
225
-
226
- Stage your design (i.e. `git add`):
227
128
 
228
- ```sh
129
+ # 2. Write design docs, then stage them
229
130
  git add workflow/REQ-2026-001/00-requirement.md workflow/REQ-2026-001/01-design.md workflow/REQ-2026-001/02-plan.md
230
- npm run req:review-codex -- 2026-001 --kind design --run
231
- ```
232
-
233
- - Codex reads the design and returns **approval** or **NEEDS_FIX**.
234
- - If NEEDS_FIX, apply the feedback, then **`git add` again โ†’ re-run the command.** Repeat until approved.
235
-
236
- ### Step 4 โ€” implement code + tests
237
131
 
238
- Once the design is approved, write the actual code and tests.
239
-
240
- ### Step 5 โ€” gate check
132
+ # 3. Design review
133
+ npm run req:review-codex -- 2026-001 --kind design --run
241
134
 
242
- Stage your changes and preview the gate status:
135
+ # 4. Implement code, then stage source files
136
+ git add <changed-source-files>
243
137
 
244
- ```sh
245
- git add <files-you-changed>
138
+ # 5. Gate check
246
139
  npm run req:doctor -- 2026-001
247
- ```
248
-
249
- - It checks several things (is the design approval valid, does the staged code match the approved code, is the working tree clean, etc.) and shows **PASS/FAIL.**
250
140
 
251
- > โš ๏ธ **Important:** `git add` **only your own code/docs.** Do **not** stage workflow-internal files like `state.json` or `responses/` (the tool manages them; staging them by mistake gets blocked at the commit step).
252
-
253
- ### Step 6 โ€” get a code review (Codex)
254
-
255
- ```sh
141
+ # 6. Implementation review
256
142
  npm run req:review-codex -- 2026-001 --kind phase --run
143
+
144
+ # 7. Commit approved code
145
+ npm run req:commit -- 2026-001 --run -m "feat: my feature"
257
146
  ```
258
147
 
259
- - Codex reviews the **implementation code.** Again, apply feedback โ†’ re-run until approved.
260
- - Once approved, `commit_allowed=true` and the commit opens.
148
+ Important: only stage code and documents you authored for the source commit. `state.json` and `responses/` are managed by the tool.
261
149
 
262
- ### Step 7 โ€” commit
150
+ For multi-line commit messages, use a file instead of `-m`.
263
151
 
264
152
  ```sh
265
- npm run req:commit -- 2026-001 --run -m "feat: implement my-feature"
153
+ npm run req:commit -- 2026-001 --run --message-file commit-message.txt
266
154
  ```
267
155
 
268
- - After passing the gate (doctor) one final time, it makes a **code commit + an evidence commit.**
269
- - If it isn't approved, or the code changed after approval, it **stops here.** (That's the heart of CommitGate.)
270
-
271
- ๐ŸŽ‰ Done! Your code is now committed safely with review, approval, and evidence all recorded.
272
-
273
156
  ---
274
157
 
275
- ## ๐Ÿ“‹ Command cheat sheet
158
+ ## Command Cheat Sheet
276
159
 
277
- | Command | What it does |
160
+ | Command | Purpose |
278
161
  |---|---|
279
- | `npx commitgate` | Install (scaffold) CommitGate into your project |
280
- | `req:new <name> --run` | Create a new ticket + branch + design docs |
281
- | `req:review-codex <num> --kind design --run` | **Design** review (Codex) |
282
- | `req:review-codex <num> --kind phase --run` | **Implementation** review (Codex) |
283
- | `req:doctor <num>` | Gate check (shows pass/fail) |
284
- | `req:commit <num> --run -m "message"` | Commit approved code (+ evidence) |
285
-
286
- > Instead of `-m "message"`, multi-line messages can be read from a file with `--message-file message.txt`.
162
+ | `npx commitgate` | Install CommitGate into a project |
163
+ | `req:new <slug> --run` | Create a REQ ticket, branch, and design docs |
164
+ | `req:review-codex <id> --kind design --run` | Review the design |
165
+ | `req:review-codex <id> --kind phase --run` | Review the implementation |
166
+ | `req:doctor <id>` | Check gate status |
167
+ | `req:commit <id> --run -m "message"` | Commit approved changes |
287
168
 
288
169
  ---
289
170
 
290
- ## โš™๏ธ Configuration (`req.config.json`, optional)
171
+ ## Configuration
291
172
 
292
- You can tweak behavior via `req.config.json` at the project root. **Without the file it works on sensible defaults**, so you can ignore it at first.
173
+ Defaults are enough for most projects. If needed, edit `req.config.json` in the project root.
293
174
 
294
175
  | Key | Default | Meaning |
295
176
  |---|---|---|
296
- | `branchPrefix` | `"feat/req-"` | Prefix for newly created branch names |
297
- | `ticketRoot` | `"workflow"` | Where ticket folders live |
298
- | `packageManager` | auto-detected | `npm` / `pnpm` / `yarn` |
299
- | `designDocs` | `00-/01-/02-*.md` | Filenames of the three design docs |
177
+ | `branchPrefix` | `"feat/req-"` | Prefix for new branches |
178
+ | `ticketRoot` | `"workflow"` | REQ ticket directory |
179
+ | `packageManager` | auto-detected | `npm`, `pnpm`, or `yarn` |
180
+ | `designDocs` | `00/01/02` docs | Design document filenames |
300
181
 
301
- Invalid values (e.g. an empty `branchPrefix`, a path that escapes the folder) are **rejected safely.**
182
+ Empty `branchPrefix` values and paths that escape the project root are rejected.
302
183
 
303
184
  ---
304
185
 
305
- ## โ“ FAQ / troubleshooting
186
+ ## FAQ
306
187
 
307
- **Q. It says the `codex` command is not found.**
308
- A. The Reviewer (Codex CLI) must be installed for reviews to run. Before it's installed, review commands don't "silently pass" โ€” they **fail clearly** (that's the intended fail-closed behavior).
188
+ **What happens if Codex CLI is missing?**
189
+ The review command fails. It is not treated as approval.
309
190
 
310
- **Q. I get an error like "staged tree != approved" at the commit step.**
311
- A. It means **the approved code and the code you currently staged (`git add`) differ.** If you changed code after approval, redo Step 6 (implementation review) to re-approve. (This safeguard prevents approval swapping.)
191
+ **Can I edit code after approval and still commit?**
192
+ No. If the staged tree changes after approval, CommitGate treats the approval as stale and requires review again.
312
193
 
313
- **Q. I get a "non-code staged not allowed (state/responses)" error.**
314
- A. You `git add`ed `state.json` or `responses/`. **Don't stage those** (the tool manages them); stage only your own code/docs.
194
+ **Why should I not stage `state.json` or `responses/`?**
195
+ They are workflow state and evidence files. Mixing them into the source commit weakens the approval binding, so `req:commit` blocks it.
315
196
 
316
- **Q. Does running `npx commitgate` twice overwrite things?**
317
- A. No. **Existing files are skipped** (idempotent). To force overwrite, add `--force`.
318
-
319
- **Q. On Windows my commit message newlines look wrong.**
320
- A. For multi-line messages, use `--message-file file.txt` instead of `-m`.
197
+ **Does running install twice overwrite files?**
198
+ No. Existing files are skipped. Use `--force` if you intentionally want to refresh them.
321
199
 
322
200
  ---
323
201
 
324
- ## ๐Ÿ”’ How is "safety" guaranteed? (fail-closed)
202
+ ## Current Scope
325
203
 
326
- CommitGate's principle is **"pass only when definitely approved; block on the slightest doubt."**
204
+ The current release is **Stage A: vendored scaffold model**. `npx commitgate` copies workflow files into the target project.
327
205
 
328
- - Design docs missing or malformed โ†’ treated as not approved
329
- - Codex not installed / review failed โ†’ not a pass, fails clearly
330
- - The approved code fingerprint differs from the current code โ†’ commit rejected
331
- - The working tree is dirty (unreviewed changes mixed in) โ†’ review/commit rejected
206
+ Future scope:
332
207
 
333
- In other words, **blocking is the default and passing is the exception**, minimizing the chance of unverified code slipping through.
208
+ - Running directly from `node_modules` as a library-style model
209
+ - Non-git VCS support
210
+ - More design document templates
211
+ - Broader Linux/macOS CI smoke coverage
334
212
 
335
213
  ---
336
214
 
337
- ## ๐Ÿ“„ License
215
+ ## License
338
216
 
339
217
  [MIT](./LICENSE) ยฉ 2026 sol5288
340
-
341
- > This workflow was extracted as a standalone package from the REQ-2026-017 portability kit of `palm-kiosk-app`, and was validated by **reviewing and approving itself through this very workflow (dogfood).**
package/README.md CHANGED
@@ -1,341 +1,217 @@
1
- # CommitGate ๐Ÿšฆ
1
+ # CommitGate
2
2
 
3
3
  ๐ŸŒ **ํ•œ๊ตญ์–ด** ยท [English](./README.en.md)
4
4
 
5
- **AI๊ฐ€ ์ง  ์ฝ”๋“œ๋ฅผ, ๋‹ค๋ฅธ AI๊ฐ€ ๋ฆฌ๋ทฐํ•˜๊ณ  ์Šน์ธํ•ด์•ผ๋งŒ ์ปค๋ฐ‹๋˜๊ฒŒ ํ•˜๋Š” "์ปค๋ฐ‹ ๊ด€๋ฌธ(gate)".**
5
+ **AI ์ฝ”๋”ฉ ๋ณ€๊ฒฝ์„ Codex ๋ฆฌ๋ทฐ ์Šน์ธ ์—†์ด๋Š” ์ปค๋ฐ‹ํ•˜์ง€ ๋ชปํ•˜๊ฒŒ ๋ง‰๋Š” ์ปค๋ฐ‹ ๊ฒŒ์ดํŠธ์ž…๋‹ˆ๋‹ค.**
6
6
 
7
- > ํ•œ ์ค„ ์š”์•ฝ: **๋งŒ๋“œ๋Š” AI(Builder)** ์™€ **๊ฒ€์‚ฌํ•˜๋Š” AI(Reviewer)** ๋ฅผ ์ง์ง€์–ด, **๋ฆฌ๋ทฐยท์Šน์ธยท์ฆ๊ฑฐ ์—†์ด๋Š” ์ปค๋ฐ‹์ด ํ†ต๊ณผํ•˜์ง€ ๋ชปํ•˜๊ฒŒ** ๋ง‰์•„์ค๋‹ˆ๋‹ค.
7
+ AI ์—์ด์ „ํŠธ๊ฐ€ ์ฝ”๋“œ๋ฅผ ๋น ๋ฅด๊ฒŒ ๋งŒ๋“ค๋”๋ผ๋„, ๋ฆฌ๋ทฐ ์—†์ด ๋ฐ”๋กœ ์ปค๋ฐ‹๋˜๋ฉด ์œ„ํ—˜ํ•ฉ๋‹ˆ๋‹ค. CommitGate๋Š” ๋ณ€๊ฒฝ์„ ํ‹ฐ์ผ“ ๋‹จ์œ„๋กœ ๋ฌถ๊ณ , Codex๊ฐ€ ์Šน์ธํ•œ staged tree๋งŒ ์ปค๋ฐ‹๋˜๊ฒŒ ํ•ฉ๋‹ˆ๋‹ค. ์Šน์ธ ํ›„ ์ฝ”๋“œ๊ฐ€ ๋ฐ”๋€Œ๊ฑฐ๋‚˜ ์ฆ๊ฑฐ๊ฐ€ ๋ถ€์กฑํ•˜๋ฉด ๊ธฐ๋ณธ์ ์œผ๋กœ ๋ง‰์Šต๋‹ˆ๋‹ค.
8
8
 
9
9
  [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
10
10
 
11
11
  ---
12
12
 
13
- ## ๐Ÿค” ์ด๊ฒŒ ๋ญ”๊ฐ€์š”? (๋น„์œ ๋กœ)
13
+ ## Quick Start
14
14
 
15
- ๊ณตํ•ญ ๋ณด์•ˆ ๊ฒ€์ƒ‰๋Œ€๋ฅผ ๋– ์˜ฌ๋ ค ๋ณด์„ธ์š”. ์•„๋ฌด๋ฆฌ ๊ธ‰ํ•ด๋„ **๊ฒ€์ƒ‰๋Œ€๋ฅผ ํ†ต๊ณผํ•˜์ง€ ์•Š์œผ๋ฉด** ํƒ‘์Šน๊ตฌ๋กœ ๊ฐˆ ์ˆ˜ ์—†์ฃ .
15
+ ์•„๋ž˜๋Š” ๊ฐ€์žฅ ์งง์€ ์‚ฌ์šฉ ๊ฒฝ๋กœ์ž…๋‹ˆ๋‹ค. ํ”„๋กœ์ ํŠธ ๋ฃจํŠธ๋Š” **git ์ €์žฅ์†Œ์ด๊ณ  `package.json`์ด ์žˆ๋Š” ํด๋”**์—ฌ์•ผ ํ•ฉ๋‹ˆ๋‹ค.
16
16
 
17
- CommitGate๋„ ๋˜‘๊ฐ™์Šต๋‹ˆ๋‹ค. ์ฝ”๋“œ๋ฅผ ์•„๋ฌด๋ฆฌ ๋งŽ์ด ๋งŒ๋“ค์–ด๋„ **"๊ฒ€์‚ฌ โ†’ ์Šน์ธ"์ด๋ผ๋Š” ๊ด€๋ฌธ์„ ํ†ต๊ณผํ•˜์ง€ ์•Š์œผ๋ฉด `git commit`์ด ๋ง‰ํž™๋‹ˆ๋‹ค.**
18
-
19
- - ๐Ÿ› ๏ธ **Builder(๋งŒ๋“œ๋Š” ์ชฝ)** โ€” ๋‹น์‹ , ๋˜๋Š” ๋‹น์‹ ์˜ AI ์ฝ”๋”ฉ ๋„๊ตฌ(์˜ˆ: Claude Code). ์š”๊ตฌ์‚ฌํ•ญ์„ ์„ค๊ณ„ํ•˜๊ณ  ์ฝ”๋“œ๋ฅผ ์งญ๋‹ˆ๋‹ค.
20
- - ๐Ÿ”Ž **Reviewer(๊ฒ€์‚ฌํ•˜๋Š” ์ชฝ)** โ€” **Codex CLI**. Builder๊ฐ€ ๋งŒ๋“  ๊ฑธ **๋…๋ฆฝ์ ์œผ๋กœ ๋‹ค์‹œ ๊ฒ€ํ† **ํ•ด์„œ ํ†ต๊ณผ/๋ณด์™„์„ ํŒ์ •ํ•ฉ๋‹ˆ๋‹ค.
21
- - ๐Ÿšฆ **CommitGate** โ€” ๊ทธ ์‚ฌ์ด์— ์„œ์„œ, **Reviewer๊ฐ€ ์Šน์ธํ•œ ์ฝ”๋“œ๋งŒ** ์ปค๋ฐ‹๋˜๊ฒŒ ํ•˜๋Š” ๊ทœ์น™(๊ด€๋ฌธ).
22
-
23
- ์ฆ‰, "ํ˜ผ์ž ๋งŒ๋“ค๊ณ  ํ˜ผ์ž ์ปค๋ฐ‹"์ด ์•„๋‹ˆ๋ผ **"๋งŒ๋“  AI โ†” ๊ฒ€์‚ฌํ•œ AI"์˜ ๊ต์ฐจ ๊ฒ€์ฆ**์„ ๊ฐ•์ œํ•ฉ๋‹ˆ๋‹ค.
24
-
25
- ## ๐ŸŽฏ ์–ด๋–ค ๋ฌธ์ œ๋ฅผ ํ‘ธ๋‚˜์š”?
26
-
27
- AI๋Š” ์ฝ”๋“œ๋ฅผ **๋น ๋ฅด๊ฒŒ** ๋งŒ๋“ค์ง€๋งŒ, ๊ฒ€์ฆ ์—†์ด ๊ทธ๋Œ€๋กœ ์ปค๋ฐ‹๋˜๋ฉด ์œ„ํ—˜ํ•ฉ๋‹ˆ๋‹ค. CommitGate๋Š”:
28
-
29
- - โœ… ๋ชจ๋“  ๋ณ€๊ฒฝ์ด **๋ฆฌ๋ทฐ๋ฅผ ๋ฐ˜๋“œ์‹œ ๊ฑฐ์น˜๊ฒŒ** ํ•ฉ๋‹ˆ๋‹ค.
30
- - โœ… ์Šน์ธ์€ **"๋ฆฌ๋ทฐํ•œ ๋ฐ”๋กœ ๊ทธ ์ฝ”๋“œ"์— ๋ฌถ์ž…๋‹ˆ๋‹ค.** (์Šน์ธ ํ›„ ๋ชฐ๋ž˜ ์ฝ”๋“œ๋ฅผ ๋ฐ”๊ฟ”์น˜๊ธฐ ๋ชป ํ•จ โ€” ์ง€๋ฌธ์ฒ˜๋Ÿผ ๋Œ€์กฐ)
31
- - โœ… ๋ฌด์–ธ๊ฐ€ ์• ๋งคํ•˜๊ฑฐ๋‚˜ ๋น ์ง€๋ฉด **์ผ๋‹จ ๋ง‰์Šต๋‹ˆ๋‹ค(fail-closed).** "ํ™•์‹คํ•  ๋•Œ๋งŒ ํ†ต๊ณผ"๊ฐ€ ๊ธฐ๋ณธ๊ฐ’์ด๋ผ ์•ˆ์ „ํ•ฉ๋‹ˆ๋‹ค.
32
- - โœ… ๋ˆ„๊ฐ€ ์–ธ์ œ ๋ฌด์—‡์„ ์Šน์ธํ–ˆ๋Š”์ง€ **์ฆ๊ฑฐ๊ฐ€ ํŒŒ์ผ๋กœ ๋‚จ์Šต๋‹ˆ๋‹ค.**
33
-
34
- ## ๐Ÿ”„ ๋™์ž‘ ํ๋ฆ„ ํ•œ๋ˆˆ์—
35
-
36
- ```
37
- โ‘  ํ‹ฐ์ผ“ ๋งŒ๋“ค๊ธฐ โ†’ โ‘ก ์„ค๊ณ„ ์ž‘์„ฑ โ†’ โ‘ข ์„ค๊ณ„ ๋ฆฌ๋ทฐ(Codex) โ†’ โ‘ฃ ์ฝ”๋“œ ๊ตฌํ˜„
38
- req:new req:review-codex
39
-
40
- โ†’ โ‘ค ๊ด€๋ฌธ ์ ๊ฒ€ โ†’ โ‘ฅ ๊ตฌํ˜„ ๋ฆฌ๋ทฐ(Codex) โ†’ โ‘ฆ ์Šน์ธ๋˜๋ฉด ์ปค๋ฐ‹
41
- req:doctor req:review-codex req:commit
17
+ ```sh
18
+ npx commitgate
19
+ npm install
20
+ codex --version
21
+ codex login status
42
22
  ```
43
23
 
44
- ๊ฐ ๋‹จ๊ณ„์—์„œ **ํ†ต๊ณผํ•˜์ง€ ๋ชปํ•˜๋ฉด ๋‹ค์Œ์œผ๋กœ ๋ชป ๋„˜์–ด๊ฐ‘๋‹ˆ๋‹ค.**
45
-
46
- ---
47
-
48
- ## ๐Ÿ“ฆ ์ค€๋น„๋ฌผ (Prerequisites)
24
+ ๊ทธ๋‹ค์Œ AI ์ฝ”๋”ฉ ์—์ด์ „ํŠธ์—๊ฒŒ ์•„๋ž˜ ํ”„๋กฌํ”„ํŠธ๋ฅผ ๋ถ™์—ฌ๋„ฃ์Šต๋‹ˆ๋‹ค.
49
25
 
50
- ์‹œ์ž‘ ์ „์— ์•„๋ž˜ 4๊ฐ€์ง€๊ฐ€ ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค. ํ„ฐ๋ฏธ๋„์—์„œ ํ•˜๋‚˜์”ฉ ํ™•์ธํ•ด ๋ณด์„ธ์š”.
26
+ ```text
27
+ ์ด ์š”์ฒญ์€ ์ผ๋ฐ˜ ๊ตฌํ˜„์œผ๋กœ ์ฒ˜๋ฆฌํ•˜์ง€ ๋ง๊ณ , ์ด ํ”„๋กœ์ ํŠธ์— ์„ค์น˜๋œ CommitGate๋ฅผ ์‚ฌ์šฉํ•ด๋ผ.
51
28
 
52
- | ํ•„์š”ํ•œ ๊ฒƒ | ํ™•์ธ ๋ช…๋ น | ์—†์œผ๋ฉด |
53
- |---|---|---|
54
- | **Git** (ํ•„์ˆ˜) | `git --version` | [git-scm.com](https://git-scm.com) ์—์„œ ์„ค์น˜ |
55
- | **Node.js 18.17+** (ํ•„์ˆ˜) | `node --version` | [nodejs.org](https://nodejs.org) ์—์„œ ์„ค์น˜ |
56
- | **Codex CLI** (๋ฆฌ๋ทฐ์šฉ) | `codex --version` | OpenAI Codex CLI ์„ค์น˜ (์—†์œผ๋ฉด ๋ฆฌ๋ทฐ๋งŒ ์•ˆ ๋˜๊ณ  ๋‚˜๋จธ์ง€๋Š” ๋จ) |
57
- | **ํŒจํ‚ค์ง€ ๋งค๋‹ˆ์ €** | `npm --version` | Node ์„ค์น˜ ์‹œ `npm`์€ ๊ธฐ๋ณธ ํฌํ•จ (๋˜๋Š” `pnpm`/`yarn`) |
58
-
59
- > ๐Ÿ’ก **Reviewer = Codex CLI** ์ž…๋‹ˆ๋‹ค. ๋ฆฌ๋ทฐ๋ฅผ ์‹ค์ œ๋กœ ๋Œ๋ฆฌ๋ ค๋ฉด Codex CLI๊ฐ€ ์„ค์น˜๋˜์–ด ์žˆ์–ด์•ผ ํ•ด์š”. ์—†์œผ๋ฉด ๋ฆฌ๋ทฐ ๋ช…๋ น์ด "์•ˆ์ „ํ•˜๊ฒŒ ์‹คํŒจ(fail-closed)"ํ•ฉ๋‹ˆ๋‹ค โ€” ์กฐ์šฉํžˆ ํ†ต๊ณผ๋˜๋Š” ์ผ์€ ์—†์Šต๋‹ˆ๋‹ค.
60
-
61
- ### ๐Ÿ”ง Codex CLI ์„ค์น˜ & ๋กœ๊ทธ์ธ (Reviewer ์ค€๋น„)
29
+ ์ƒˆ REQ ํ‹ฐ์ผ“์„ ๋งŒ๋“ค๊ณ  ๋‹ค์Œ ํ๋ฆ„์„ ๋๊นŒ์ง€ ์ง„ํ–‰ํ•ด๋ผ:
30
+ req:new โ†’ ์„ค๊ณ„๋ฌธ์„œ ์ž‘์„ฑ โ†’ Codex design ๋ฆฌ๋ทฐ โ†’ ๊ตฌํ˜„ยทํ…Œ์ŠคํŠธ โ†’ req:doctor โ†’ Codex phase ๋ฆฌ๋ทฐ โ†’ req:commit
62
31
 
63
- CommitGate์˜ ๋ฆฌ๋ทฐ๋Š” **OpenAI Codex CLI**๊ฐ€ ๋‹ด๋‹นํ•ฉ๋‹ˆ๋‹ค. ์•„๋ž˜ 3๋‹จ๊ณ„๋ฉด ๋๋‚ฉ๋‹ˆ๋‹ค.
32
+ ์ž๋™์œผ๋กœ ์ง„ํ–‰ํ•  ๊ฒƒ:
33
+ - NEEDS_FIX๊ฐ€ ๋‚˜์˜ค๋ฉด ์ˆ˜์ •ํ•˜๊ณ  ์žฌ๋ฆฌ๋ทฐํ•ด ์Šน์ธ๊นŒ์ง€ ๋ฐ˜๋ณตํ•œ๋‹ค.
34
+ - ๋ฆฌ๋ทฐ ๋Œ€์ƒ์€ git add ํ•œ ํŒŒ์ผ๋งŒ์ด๋‹ค.
35
+ - `state.json`๊ณผ `responses/`๋Š” ์ง์ ‘ `git add`ํ•˜์ง€ ์•Š๋Š”๋‹ค.
64
36
 
65
- **โ‘  ์„ค์น˜**
37
+ ๋ฉˆ์ถฐ์„œ ํ™•์ธ๋ฐ›์„ ๋•Œ:
38
+ - req:commit --run ์ง์ „
39
+ - main ๋ณ‘ํ•ฉ ๋˜๋Š” push ์ง์ „
40
+ - reset, clean, force push ๊ฐ™์€ destructive ์ž‘์—… ์ „
41
+ - ์š”๊ตฌ์‚ฌํ•ญ ๋ฒ”์œ„๋ฅผ ๋ฐ”๊ฟ”์•ผ ํ•  ๋•Œ
42
+ - Codex ๋ฆฌ๋ทฐ๊ฐ€ 3๋ผ์šด๋“œ๋ฅผ ๋„˜์–ด๋„ ์Šน์ธ๋˜์ง€ ์•Š์„ ๋•Œ
66
43
 
67
- ```sh
68
- # npm (๋ชจ๋“  OS)
69
- npm install -g @openai/codex
70
-
71
- # ๋˜๋Š” macOS Homebrew
72
- brew install codex
44
+ ์š”๊ตฌ์‚ฌํ•ญ:
45
+ - ๋ฌด์—‡์„:
46
+ - ์™œ:
47
+ - ์ œ์•ฝ:
48
+ - ์™„๋ฃŒ ๊ธฐ์ค€:
73
49
  ```
74
50
 
75
- ์„ค์น˜ ํ™•์ธ:
51
+ ์ฒซ ์‘๋‹ต์€ ๋ณดํ†ต ์ด๋ ‡๊ฒŒ ๋‚˜์™€์•ผ ํ•ฉ๋‹ˆ๋‹ค.
76
52
 
77
- ```sh
78
- codex --version # ์˜ˆ: codex-cli 0.4x.x
53
+ ```text
54
+ REQ-2026-002 ๋ฐœํ–‰
55
+ ๋ธŒ๋žœ์น˜: feat/req-2026-002-profile-edit-api
56
+ phase:
57
+ - phase-1: PATCH /profile ๊ตฌํ˜„
58
+ - phase-2: ํ…Œ์ŠคํŠธ์™€ ํšŒ๊ท€ ํ™•์ธ
59
+ ํ†ต์ œ์ : req:commit --run ์ง์ „, push ์ง์ „
79
60
  ```
80
61
 
81
- **โ‘ก ๋กœ๊ทธ์ธ** โ€” ๋‘˜ ์ค‘ ํŽธํ•œ ๋ฐฉ๋ฒ• ํ•˜๋‚˜
82
-
83
- - **๋ฐฉ๋ฒ• A. ChatGPT ๊ณ„์ •์œผ๋กœ (๊ถŒ์žฅ, ๋ธŒ๋ผ์šฐ์ €)**
84
- ```sh
85
- codex login
86
- ```
87
- ๋ธŒ๋ผ์šฐ์ €๊ฐ€ ์—ด๋ฆฌ๋ฉด ChatGPT ๊ณ„์ •์œผ๋กœ ๋กœ๊ทธ์ธ โ†’ ํ„ฐ๋ฏธ๋„๋กœ ๋Œ์•„์˜ค๋ฉด ์™„๋ฃŒ.
62
+ ์ดํ›„์—๋Š” ์—์ด์ „ํŠธ๊ฐ€ ์„ค๊ณ„, ๊ตฌํ˜„, ํ…Œ์ŠคํŠธ, Codex ๋ฆฌ๋ทฐ๋ฅผ ์ง„ํ–‰ํ•ฉ๋‹ˆ๋‹ค. ์‚ฌ์šฉ์ž๋Š” ์ปค๋ฐ‹์ด๋‚˜ push ๊ฐ™์€ ํ†ต์ œ์ ์—์„œ๋งŒ ํ™•์ธํ•˜๋ฉด ๋ฉ๋‹ˆ๋‹ค.
88
63
 
89
- - **๋ฐฉ๋ฒ• B. OpenAI API ํ‚ค๋กœ**
90
- ```sh
91
- # ํ™˜๊ฒฝ๋ณ€์ˆ˜๋กœ (๊ฐ€์žฅ ๊ฐ„๋‹จ)
92
- export OPENAI_API_KEY=sk-... # Windows PowerShell: $env:OPENAI_API_KEY="sk-..."
64
+ ---
93
65
 
94
- # ๋˜๋Š” ํ‚ค๋ฅผ Codex์— ์ €์žฅ
95
- printenv OPENAI_API_KEY | codex login --with-api-key
96
- ```
97
- API ํ‚ค๋Š” [platform.openai.com](https://platform.openai.com/api-keys) ์—์„œ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค.
66
+ ## ๋ฌด์—‡์„ ๋ณด์žฅํ•˜๋‚˜์š”?
98
67
 
99
- **โ‘ข ๋กœ๊ทธ์ธ ํ™•์ธ**
68
+ CommitGate๊ฐ€ ๋ง‰๋Š” ๊ฒƒ์€ ๋‹จ์ˆœํ•œ ๋ช…๋ น ์‹ค์ˆ˜๊ฐ€ ์•„๋‹ˆ๋ผ **๋ฆฌ๋ทฐ๋ฐ›์ง€ ์•Š์€ ๋ณ€๊ฒฝ์ด ์ปค๋ฐ‹๋˜๋Š” ์ƒํ™ฉ**์ž…๋‹ˆ๋‹ค.
100
69
 
101
- ```sh
102
- codex login status # ๋กœ๊ทธ์ธ ์ƒํƒœ ํ‘œ์‹œ
103
- codex doctor # ์„ค์น˜ยท์ธ์ฆยทํ™˜๊ฒฝ ์ข…ํ•ฉ ์ง„๋‹จ(๋ฌธ์ œ ์žˆ์œผ๋ฉด ์›์ธ ์•ˆ๋‚ด)
104
- ```
70
+ - Codex ๋ฆฌ๋ทฐ๊ฐ€ ์‹คํŒจํ•˜๊ฑฐ๋‚˜ ์—†์œผ๋ฉด ์ปค๋ฐ‹ํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค.
71
+ - ์Šน์ธ๋œ staged tree์™€ ์ง€๊ธˆ ์ปค๋ฐ‹ํ•˜๋ ค๋Š” staged tree๊ฐ€ ๋‹ค๋ฅด๋ฉด ๋ง‰์Šต๋‹ˆ๋‹ค.
72
+ - `state.json`, `responses/` ๊ฐ™์€ ์›Œํฌํ”Œ๋กœ ๋‚ด๋ถ€ ํŒŒ์ผ์„ source ์ปค๋ฐ‹์— ์„ž์œผ๋ฉด ๋ง‰์Šต๋‹ˆ๋‹ค.
73
+ - Codex CLI๊ฐ€ ์—†๊ฑฐ๋‚˜ ์‹คํ–‰์— ์‹คํŒจํ•˜๋ฉด ์กฐ์šฉํžˆ ํ†ต๊ณผํ•˜์ง€ ์•Š๊ณ  ์‹คํŒจํ•ฉ๋‹ˆ๋‹ค.
74
+ - ์Šน์ธ ์‘๋‹ต๊ณผ ์ฆ๊ฑฐ ํŒŒ์ผ์€ `workflow/REQ-.../responses/`์— ๋‚จ์Šต๋‹ˆ๋‹ค.
105
75
 
106
- > โœ… `codex --version` ๊ณผ `codex login status` ๊ฐ€ ์ •์ƒ์ด๋ฉด ๋ฆฌ๋ทฐ ์ค€๋น„ ๋. ์ด์ œ `npx commitgate` ๋กœ ๋„˜์–ด๊ฐ€์„ธ์š”.
107
- > โš ๏ธ Windows์—์„œ `codex` ๋ช…๋ น์„ ๋ชป ์ฐพ์œผ๋ฉด **์ƒˆ ํ„ฐ๋ฏธ๋„**์„ ์—ด์–ด PATH๋ฅผ ์ƒˆ๋กœ ์ฝ๊ฒŒ ํ•˜์„ธ์š”(์ „์—ญ ์„ค์น˜ ์งํ›„ ํ”ํ•œ ๋ฌธ์ œ).
76
+ ํ•œ ์ค„๋กœ ๋งํ•˜๋ฉด, **ํ™•์‹คํžˆ ์Šน์ธ๋œ ๋ณ€๊ฒฝ๋งŒ ํ†ต๊ณผํ•˜๊ณ  ์• ๋งคํ•˜๋ฉด ๋ฉˆ์ถ”๋Š” ๋ฐฉ์‹**์ž…๋‹ˆ๋‹ค.
108
77
 
109
78
  ---
110
79
 
111
- ## ๐Ÿš€ ์„ค์น˜ (๋”ฑ ํ•œ ์ค„)
112
-
113
- **๋‹น์‹ ์˜ ํ”„๋กœ์ ํŠธ ํด๋”**(= git ์ €์žฅ์†Œ, `package.json` ์žˆ๋Š” ๊ณณ)์—์„œ:
80
+ ## ์„ค์น˜๊ฐ€ ํ•˜๋Š” ์ผ
114
81
 
115
- ```sh
116
- npx commitgate
117
- ```
82
+ `npx commitgate`๋Š” ๋Œ€์ƒ ํ”„๋กœ์ ํŠธ์— ์•„๋ž˜ ํŒŒ์ผ๊ณผ ์„ค์ •์„ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. ๊ธฐ์กด ํŒŒ์ผ์€ ๊ธฐ๋ณธ์ ์œผ๋กœ ๋ฎ์–ด์“ฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค.
118
83
 
119
- ์ด ๋ช…๋ น์ด ์ž๋™์œผ๋กœ ํ•ด์ฃผ๋Š” ์ผ (๊ธฐ์กด ํŒŒ์ผ์€ **๋ฎ์–ด์“ฐ์ง€ ์•Š์•„์š”**):
120
-
121
- 1. ์›Œํฌํ”Œ๋กœ ์Šคํฌ๋ฆฝํŠธ(`scripts/req/`)์™€ ์Šคํ‚ค๋งˆ๋ฅผ ๋ณต์‚ฌํ•ฉ๋‹ˆ๋‹ค.
122
- 2. `req.config.json`(์„ค์ • ํŒŒ์ผ)์„ ๋งŒ๋“ค์–ด ๋‘ก๋‹ˆ๋‹ค.
123
- 3. `package.json`์— `req:*` ๋ช…๋ น๋“ค๊ณผ ํ•„์š”ํ•œ devDependencies(`tsx`, `ajv`, `cross-spawn`)๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค.
124
- 4. `AGENTS.md`(Reviewer๊ฐ€ ์ฝ๋Š” ๊ทœ์น™ ํŒŒ์ผ)๊ฐ€ ์—†์œผ๋ฉด ํ…œํ”Œ๋ฆฟ์„ ๋งŒ๋“ค์–ด ์ค๋‹ˆ๋‹ค.
84
+ | ์ถ”๊ฐ€ ํ•ญ๋ชฉ | ์„ค๋ช… |
85
+ |---|---|
86
+ | `scripts/req/` | `req:new`, `req:review-codex`, `req:doctor`, `req:commit` ์Šคํฌ๋ฆฝํŠธ |
87
+ | `workflow/*.schema.json` | Codex ์‘๋‹ต๊ณผ ์„ค์ • ๊ฒ€์ฆ ์Šคํ‚ค๋งˆ |
88
+ | `req.config.json` | ํ”„๋กœ์ ํŠธ๋ณ„ ์„ค์ • |
89
+ | `AGENTS.md` | ์—์ด์ „ํŠธ์™€ Reviewer๊ฐ€ ์ฝ๋Š” ๊ทœ์น™ ํ…œํ”Œ๋ฆฟ |
90
+ | `package.json` ์Šคํฌ๋ฆฝํŠธ | `req:*` ๋ช…๋ น๊ณผ ํ•„์š”ํ•œ devDependencies |
125
91
 
126
- ์„ค์น˜ ํ›„, ๋ฐฉ๊ธˆ ์ถ”๊ฐ€๋œ ์˜์กด์„ฑ์„ ๋ฐ›์Šต๋‹ˆ๋‹ค:
92
+ ๋ฏธ๋ฆฌ๋ณด๊ธฐ๋งŒ ํ•˜๋ ค๋ฉด:
127
93
 
128
94
  ```sh
129
- npm install
95
+ npx commitgate --dry-run
130
96
  ```
131
97
 
132
- > `--dry-run` ์„ ๋ถ™์ด๋ฉด **์‹ค์ œ๋กœ ๋ฐ”๊พธ์ง€ ์•Š๊ณ ** ๋ฌด์—‡์„ ํ• ์ง€ ๋ฏธ๋ฆฌ ๋ณผ ์ˆ˜ ์žˆ์–ด์š”: `npx commitgate --dry-run`
133
-
134
98
  ---
135
99
 
136
- ## ๐Ÿค– ์‚ฌ์šฉ๋ฒ• โ€” AI ์—์ด์ „ํŠธ์—๊ฒŒ ํ”„๋กฌํ”„ํŠธ๋กœ ๋งก๊ธฐ๊ธฐ (๊ถŒ์žฅ)
137
-
138
- ์†”์งํžˆ, `req:new โ†’ ๋ฆฌ๋ทฐ โ†’ ๊ตฌํ˜„ โ†’ ๋ฆฌ๋ทฐ โ†’ ์ปค๋ฐ‹`์„ **์†์œผ๋กœ ํ•˜๋‚˜์”ฉ ์น˜๋Š” ์‚ฌ๋žŒ์€ ์—†์Šต๋‹ˆ๋‹ค.** ํ”ผ๊ณคํ•˜๋‹ˆ๊นŒ์š”.
139
-
140
- CommitGate์˜ ์ง„์งœ ์‚ฌ์šฉ๋ฒ•์€ ์ด๊ฒ๋‹ˆ๋‹ค: **๋‹น์‹ ์˜ AI ์ฝ”๋”ฉ ์—์ด์ „ํŠธ์—๊ฒŒ "์š”๊ตฌ์‚ฌํ•ญ"๊ณผ "์ด ์›Œํฌํ”Œ๋กœ๋ฅผ ์“ฐ๋ผ"๋Š” ํ”„๋กฌํ”„ํŠธ๋ฅผ ๋˜์ง€๋ฉด, ์—์ด์ „ํŠธ๊ฐ€ ์•Œ์•„์„œ ์ „ ๊ณผ์ •์„ ๊ตด๋ฆฝ๋‹ˆ๋‹ค.** ๋‹น์‹ ์€ **ํ†ต์ œ์ (์ปค๋ฐ‹ยท๋จธ์ง€ยทํ‘ธ์‹œ ๋“ฑ)์—์„œ๋งŒ** ์Šน์ธํ•˜๋ฉด ๋ฉ๋‹ˆ๋‹ค.
141
-
142
- ### ์ด ๋ฐฉ์‹์˜ ์ „์ œ
143
- - **์…ธ ๋ช…๋ น์„ ์‹คํ–‰ํ•  ์ˆ˜ ์žˆ๋Š” AI ์ฝ”๋”ฉ ์—์ด์ „ํŠธ** โ€” Claude Code, Cursor(agent), Codex CLI ๋“ฑ. (๋‹น์‹ ์˜ ์ €์žฅ์†Œ์—์„œ ํ„ฐ๋ฏธ๋„ ๋ช…๋ น์„ ์ง์ ‘ ๋Œ๋ฆด ์ˆ˜ ์žˆ์–ด์•ผ ํ•จ)
144
- - **Codex CLI ์„ค์น˜** โ€” ๋ฆฌ๋ทฐ์–ด(Reviewer) ์—ญํ• . ์—†์œผ๋ฉด ๋ฆฌ๋ทฐ ๋‹จ๊ณ„๊ฐ€ fail-closed๋กœ ๋ฉˆ์ถฅ๋‹ˆ๋‹ค.
145
- - **`AGENTS.md` ์ฑ„์šฐ๊ธฐ** โ€” `npx commitgate`๊ฐ€ ๋งŒ๋“  ํ…œํ”Œ๋ฆฟ์— ๋‹น์‹  ํ”„๋กœ์ ํŠธ์˜ ๊ทœ์น™(์ฝ”๋”ฉ ์ปจ๋ฒค์…˜ยทํ…Œ์ŠคํŠธ ๋ช…๋ น ๋“ฑ)์„ ์ ์–ด๋‘๋ฉด ๋ฆฌ๋ทฐ ํ’ˆ์งˆ์ด ์˜ฌ๋ผ๊ฐ‘๋‹ˆ๋‹ค.
146
-
147
- ### 3๋‹จ๊ณ„๋ฉด ๋
148
- 1. ์•„๋ž˜ **ํ”„๋กฌํ”„ํŠธ ํ…œํ”Œ๋ฆฟ**์„ ๋ณต์‚ฌํ•˜๊ณ , ๋งจ ์•„๋ž˜ `[์š”๊ตฌ์‚ฌํ•ญ]` ์นธ์„ ๋‹น์‹  ์š”๊ตฌ๋กœ ์ฑ„์›๋‹ˆ๋‹ค.
149
- 2. ์ „์ฒด๋ฅผ **AI ์—์ด์ „ํŠธ ๋Œ€ํ™”์ฐฝ์— ๊ทธ๋Œ€๋กœ ๋ถ™์—ฌ๋„ฃ์Šต๋‹ˆ๋‹ค.**
150
- 3. ์—์ด์ „ํŠธ๊ฐ€ **์ฒซ ์‘๋‹ต์œผ๋กœ REQ ๋ฒˆํ˜ธยท๋ธŒ๋žœ์น˜ยทphase ๊ณ„ํšยทํ†ต์ œ์ **๋งŒ ๋ณด๊ณ ํ•ฉ๋‹ˆ๋‹ค. ์ดํ›„์—” **ํ†ต์ œ์ ์—์„œ๋งŒ** ๋‹น์‹ ์—๊ฒŒ ํ™•์ธ์„ ๋ฐ›์Šต๋‹ˆ๋‹ค โ€” ๋‚˜๋จธ์ง€(๊ตฌํ˜„ยทํ…Œ์ŠคํŠธยทCodex ๋ฆฌ๋ทฐยทNEEDS_FIX ๋ฐ˜์˜ยท์žฌ๋ฆฌ๋ทฐ)๋Š” ์ž๋™์ž…๋‹ˆ๋‹ค.
151
-
152
- ### ๐Ÿ“‹ ๋ณต์‚ฌํ•ด์„œ ์“ฐ๋Š” ํ”„๋กฌํ”„ํŠธ ํ…œํ”Œ๋ฆฟ
100
+ ## ์ค€๋น„๋ฌผ
153
101
 
154
- ````text
155
- ์ด ์š”์ฒญ์€ ์ผ๋ฐ˜ ๊ตฌํ˜„์œผ๋กœ ์ฒ˜๋ฆฌํ•˜์ง€ ๋ง๊ณ , ๋ฐ˜๋“œ์‹œ ์ด ํ”„๋กœ์ ํŠธ์— ์„ค์น˜๋œ CommitGate(AI REQ workflow)๋ฅผ ์‚ฌ์šฉํ•ด๋ผ.
156
-
157
- ์•„๋ž˜ [์š”๊ตฌ์‚ฌํ•ญ]์œผ๋กœ ์ƒˆ REQ ํ‹ฐ์ผ“์„ ๋ฐœํ–‰ํ•˜๊ณ  ๋‹ค์Œ ํ๋ฆ„์„ ๋๊นŒ์ง€ ํƒœ์›Œ๋ผ:
158
- req:new โ†’ ์„ค๊ณ„๋ฌธ์„œ(00/01/02) ์ž‘์„ฑ โ†’ req:review-codex(design ๋ฆฌ๋ทฐ)
159
- โ†’ phase ๊ตฌํ˜„ยทํ…Œ์ŠคํŠธ โ†’ req:doctor(๊ฒŒ์ดํŠธ) โ†’ req:review-codex(phase ๋ฆฌ๋ทฐ) โ†’ req:commit
160
-
161
- [์ž๋™์œผ๋กœ ์ง„ํ–‰ํ•  ๊ฒƒ]
162
- - ์Šน์ธ๋œ phase ๋ฒ”์œ„ ์•ˆ์—์„œ ๊ตฌํ˜„ยทํ…Œ์ŠคํŠธยทcodex-request ์ •ํ•ฉยทNEEDS_FIX ๋ฐ˜์˜ยท์žฌ๋ฆฌ๋ทฐ(resume)๋Š” ์ž๋™์œผ๋กœ ์ง„ํ–‰ํ•ด๋ผ. ๋งค๋ฒˆ ํ™•์ธ๋ฐ›์ง€ ๋งˆ๋ผ.
163
- - Codex๊ฐ€ NEEDS_FIX๋ฅผ ์ฃผ๋ฉด ์ง€์ ์„ ๋ฐ˜์˜ํ•˜๊ณ  ์žฌ๋ฆฌ๋ทฐ๋ฅผ ๋Œ๋ ค ์Šน์ธ๊นŒ์ง€ ๋ฐ˜๋ณตํ•ด๋ผ(phase๋‹น ์ตœ๋Œ€ 3๋ผ์šด๋“œ).
164
- - ๋ฆฌ๋ทฐ ๋Œ€์ƒ์€ git add ํ•œ ๊ฒƒ๋งŒ์ด๋‹ค. state.jsonยทresponses/ ๋Š” ์ ˆ๋Œ€ git add ํ•˜์ง€ ๋งˆ๋ผ(๋„๊ตฌ๊ฐ€ ๊ด€๋ฆฌํ•œ๋‹ค).
165
-
166
- [๋ฉˆ์ถฐ์„œ ์‚ฌ๋žŒ ํ™•์ธ์„ ๋ฐ›์„ ํ†ต์ œ์  โ€” ์—ฌ๊ธฐ์„œ๋งŒ ๋ฉˆ์ถฐ๋ผ]
167
- - req:commit --run ์ง์ „ (์‹ค์ œ ์ปค๋ฐ‹ / HIGH ์˜ํ–ฅ)
168
- - main ๋ณ‘ํ•ฉ ๋˜๋Š” git push ์ง์ „
169
- - resetยทcleanยทforce push ๋“ฑ destructive ์ž‘์—…
170
- - ์„ค๊ณ„ ๋ฒ”์œ„ ๋ณ€๊ฒฝ ๋˜๋Š” [์š”๊ตฌ์‚ฌํ•ญ]์— ์—†๋Š” ๊ธฐ๋Šฅ ์ถ”๊ฐ€๊ฐ€ ํ•„์š”ํ•  ๋•Œ
171
- - Codex ๋ฆฌ๋ทฐ๊ฐ€ 3๋ผ์šด๋“œ๋ฅผ ๋„˜๊ฒจ๋„ ์Šน์ธ ์•ˆ ๋˜๊ฑฐ๋‚˜ ํŒ๋‹จ์ด ๋ถˆ๋ช…ํ™•ํ•  ๋•Œ
172
- - git ์ €์žฅ์†Œ๊ฐ€ ์•„๋‹ˆ๊ฑฐ๋‚˜ Codex CLIยทNodeยทํŒจํ‚ค์ง€๋งค๋‹ˆ์ € ์ „์ œ๊ฐ€ ์—†์–ด fail-closed ํ•ด์•ผ ํ•  ๋•Œ
173
-
174
- [์ฒซ ์‘๋‹ต] REQ ๋ฒˆํ˜ธ, ๋ธŒ๋žœ์น˜, phase ๊ณ„ํš, ํ†ต์ œ์ ๋งŒ ๊ฐ„๋‹จํžˆ ๋ณด๊ณ ํ•ด๋ผ. ๊ทธ ๋’ค๋ถ€ํ„ฐ๋Š” ํ†ต์ œ์ ์—์„œ๋งŒ ๋ฉˆ์ถฐ๋ผ.
175
-
176
- [์š”๊ตฌ์‚ฌํ•ญ]
177
- - ๋ฌด์—‡์„: (์˜ˆ) ์‚ฌ์šฉ์ž ํ”„๋กœํ•„ ํŽธ์ง‘ API ์ถ”๊ฐ€
178
- - ์™œ: (์˜ˆ) ์ง€๊ธˆ์€ ์ด๋ฆ„๋งŒ ์ˆ˜์ • ๊ฐ€๋Šฅ โ€” ์ด๋ฉ”์ผยท์†Œ๊ฐœ๋„ ํŽธ์ง‘ ํ•„์š”
179
- - ์ œ์•ฝ: (์˜ˆ) ๊ธฐ์กด ์ธ์ฆ ๋ฏธ๋“ค์›จ์–ด ์žฌ์‚ฌ์šฉ, ์ด๋ฉ”์ผ ํ˜•์‹ ๊ฒ€์ฆ, ์™ธ๋ถ€ ๋ผ์ด๋ธŒ๋Ÿฌ๋ฆฌ ์ถ”๊ฐ€ ๊ธˆ์ง€
180
- - ์™„๋ฃŒ ๊ธฐ์ค€: (์˜ˆ) PATCH /profile ๋™์ž‘ + ๋‹จ์œ„ ํ…Œ์ŠคํŠธ ํ†ต๊ณผ + ๊ธฐ์กด ํ…Œ์ŠคํŠธ ๋ฌด์†์ƒ
181
- ````
182
-
183
- > ์œ„ `[์š”๊ตฌ์‚ฌํ•ญ]` ์˜ˆ์‹œ๋Š” **์ƒ˜ํ”Œ์ผ ๋ฟ**์ž…๋‹ˆ๋‹ค. 4์ค„(๋ฌด์—‡์„/์™œ/์ œ์•ฝ/์™„๋ฃŒ ๊ธฐ์ค€)์„ ๋‹น์‹  ์š”๊ตฌ๋กœ ๋ฐ”๊พธ๊ธฐ๋งŒ ํ•˜๋ฉด ๋ฉ๋‹ˆ๋‹ค. ์š”๊ตฌ๊ฐ€ ํฌ๋ฉด phase๊ฐ€ ์—ฌ๋Ÿฌ ๊ฐœ๋กœ ์ชผ๊ฐœ์ง€๊ณ , ๊ฐ phase๋งˆ๋‹ค ๋ฆฌ๋ทฐยท๊ฒŒ์ดํŠธ๋ฅผ ๊ฑฐ์นฉ๋‹ˆ๋‹ค.
102
+ | ํ•„์š” | ํ™•์ธ ๋ช…๋ น | ๋น„๊ณ  |
103
+ |---|---|---|
104
+ | Git | `git --version` | ํ•„์ˆ˜ |
105
+ | Node.js 18.17+ | `node --version` | ํ•„์ˆ˜ |
106
+ | npm, pnpm, yarn ์ค‘ ํ•˜๋‚˜ | `npm --version` | npm ๊ธฐ์ค€์œผ๋กœ ์•ˆ๋‚ด |
107
+ | Codex CLI | `codex --version` | ๋ฆฌ๋ทฐ ์‹คํ–‰์— ํ•„์š” |
184
108
 
185
- ### ์—์ด์ „ํŠธ๊ฐ€ ๋ณด๊ณ ํ•˜๋Š” ์ฒซ ์‘๋‹ต ์˜ˆ์‹œ
109
+ Codex CLI๊ฐ€ ์—†๋‹ค๋ฉด:
186
110
 
187
- ```
188
- REQ-2026-002 ๋ฐœํ–‰ ยท ๋ธŒ๋žœ์น˜ feat/req-2026-002-profile-edit-api
189
- phase ๊ณ„ํš:
190
- - phase-1: PATCH /profile ํ•ธ๋“ค๋Ÿฌ + ์œ ํšจ์„ฑ ๊ฒ€์ฆ
191
- - phase-2: ๋‹จ์œ„ ํ…Œ์ŠคํŠธ + ํšŒ๊ท€
192
- ํ†ต์ œ์ : design ์Šน์ธ ํ›„ phase๋ณ„ ์ง„ํ–‰ / req:commit --run ์ง์ „ ํ™•์ธ / push๋Š” ๋ณ„๋„ ์Šน์ธ
193
- โ†’ ์„ค๊ณ„๋ฌธ์„œ ์ž‘์„ฑ๋ถ€ํ„ฐ ์ง„ํ–‰ํ•ฉ๋‹ˆ๋‹ค. design ๋ฆฌ๋ทฐ ํ†ต๊ณผํ•˜๋ฉด ๊ตฌํ˜„์œผ๋กœ ๋„˜์–ด๊ฐ‘๋‹ˆ๋‹ค.
111
+ ```sh
112
+ npm install -g @openai/codex
113
+ codex login
114
+ codex login status
194
115
  ```
195
116
 
196
- ์ด์ œ ๋‹น์‹ ์€ ํ†ต์ œ์  ์•Œ๋ฆผ์ด ์˜ฌ ๋•Œ๊นŒ์ง€ **๊ธฐ๋‹ค๋ฆฌ๊ธฐ๋งŒ** ํ•˜๋ฉด ๋ฉ๋‹ˆ๋‹ค. ์ปค๋ฐ‹ ์ง์ „์— "์ด๋Œ€๋กœ ์ปค๋ฐ‹ํ• ๊นŒ์š”?" ๋ฌผ์œผ๋ฉด ํ™•์ธํ•ด ์ฃผ๋ฉด ๋˜๊ณ ์š”.
117
+ Windows์—์„œ ์„ค์น˜ ์งํ›„ `codex` ๋ช…๋ น์„ ๋ชป ์ฐพ์œผ๋ฉด ์ƒˆ ํ„ฐ๋ฏธ๋„์„ ์—ด์–ด PATH๋ฅผ ๋‹ค์‹œ ์ฝ๊ฒŒ ํ•˜์„ธ์š”.
197
118
 
198
119
  ---
199
120
 
200
- ## ๐Ÿ”ง ๋ถ€๋ก: ์›Œํฌํ”Œ๋กœ๊ฐ€ ๋‚ด๋ถ€์—์„œ ์‹ค์ œ๋กœ ํ•˜๋Š” ์ผ (์ˆ˜๋™ ๋‹จ๊ณ„)
121
+ ## ์ˆ˜๋™ ๋ช…๋ น
201
122
 
202
- > ์œ„ ํ”„๋กฌํ”„ํŠธ ๋ฐฉ์‹์ด๋ฉด ์•„๋ž˜ ๋ช…๋ น์„ **์ง์ ‘ ์น  ํ•„์š”๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค** โ€” ์—์ด์ „ํŠธ๊ฐ€ ์•Œ์•„์„œ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค.
203
- > ์•„๋ž˜๋Š” ์›Œํฌํ”Œ๋กœ๊ฐ€ ๋‚ด๋ถ€์—์„œ ๋Œ๋ฆฌ๋Š” ์‹ค์ œ ๋ช…๋ น๋“ค์ž…๋‹ˆ๋‹ค. **๋™์ž‘ ์ดํ•ดยท๋””๋ฒ„๊น…ยท์ˆ˜๋™ ์‹คํ–‰**์ด ํ•„์š”ํ•  ๋•Œ๋งŒ ์ฐธ๊ณ ํ•˜์„ธ์š”.
204
-
205
- ์ž‘์€ ๊ธฐ๋Šฅ ํ•˜๋‚˜๋ฅผ ์˜ˆ๋กœ, ์ „์ฒด ํ๋ฆ„์„ ๊ทธ๋Œ€๋กœ ๋ฐŸ์•„ ๋ด…๋‹ˆ๋‹ค. (๋ช…๋ น์€ `npm` ๊ธฐ์ค€์ด๋ฉฐ, `npm run` ๋’ค ์ธ์ž๋Š” `--` ๋‹ค์Œ์— ์”๋‹ˆ๋‹ค. `pnpm`์„ ์“ฐ๋ฉด `pnpm req:new my-feature --run` ์ฒ˜๋Ÿผ `--` ์—†์ด ๋ฉ๋‹ˆ๋‹ค.)
206
-
207
- ### 1๋‹จ๊ณ„ โ€” ์ž‘์—… ํ‹ฐ์ผ“ ๋งŒ๋“ค๊ธฐ
123
+ ๋Œ€๋ถ€๋ถ„์˜ ์‚ฌ์šฉ์ž๋Š” ์œ„ ํ”„๋กฌํ”„ํŠธ ๋ฐฉ์‹์œผ๋กœ ์ถฉ๋ถ„ํ•ฉ๋‹ˆ๋‹ค. ์•„๋ž˜๋Š” ๋‚ด๋ถ€์—์„œ ์–ด๋–ค ๋ช…๋ น์ด ์‹คํ–‰๋˜๋Š”์ง€ ์ดํ•ดํ•˜๊ฑฐ๋‚˜ ์ง์ ‘ ๋””๋ฒ„๊น…ํ•  ๋•Œ๋งŒ ๋ณด๋ฉด ๋ฉ๋‹ˆ๋‹ค.
208
124
 
209
125
  ```sh
126
+ # 1. ํ‹ฐ์ผ“๊ณผ ๋ธŒ๋žœ์น˜ ์ƒ์„ฑ
210
127
  npm run req:new -- my-feature --run
211
- ```
212
-
213
- - ์ƒˆ ๋ธŒ๋žœ์น˜(`feat/req-...`)๊ฐ€ ์ƒ๊ธฐ๊ณ , `workflow/REQ-2026-001/` ํด๋”์— ์„ค๊ณ„ ๋ฌธ์„œ 3์ข…์ด ๋งŒ๋“ค์–ด์ง‘๋‹ˆ๋‹ค.
214
- - ์ถœ๋ ฅ์— **ํ‹ฐ์ผ“ ๋ฒˆํ˜ธ**(์˜ˆ: `REQ-2026-001`)๊ฐ€ ๋‚˜์˜ต๋‹ˆ๋‹ค. ์ดํ›„ ๋ช…๋ น์—์„  ๋ฒˆํ˜ธ๋งŒ ์”๋‹ˆ๋‹ค โ†’ `2026-001`
215
-
216
- ### 2๋‹จ๊ณ„ โ€” ์„ค๊ณ„ ๋ฌธ์„œ ์ž‘์„ฑ
217
-
218
- `workflow/REQ-2026-001/` ์•ˆ์˜ ์„ธ ํŒŒ์ผ์„ ์ฑ„์›๋‹ˆ๋‹ค:
219
-
220
- - `00-requirement.md` โ€” **๋ฌด์—‡์„** ์™œ ๋งŒ๋“œ๋Š”๊ฐ€
221
- - `01-design.md` โ€” **์–ด๋–ป๊ฒŒ** ๋งŒ๋“ค ๊ฒƒ์ธ๊ฐ€
222
- - `02-plan.md` โ€” ์–ด๋–ค **์ˆœ์„œ/๋‹จ๊ณ„**๋กœ ์ง„ํ–‰ํ•  ๊ฒƒ์ธ๊ฐ€
223
-
224
- ### 3๋‹จ๊ณ„ โ€” ์„ค๊ณ„ ๋ฆฌ๋ทฐ ๋ฐ›๊ธฐ (Codex)
225
-
226
- ์ž‘์„ฑํ•œ ์„ค๊ณ„๋ฅผ ๊ฒ€์‚ฌ๋Œ€์— ์˜ฌ๋ฆฝ๋‹ˆ๋‹ค(= `git add`):
227
128
 
228
- ```sh
129
+ # 2. ์„ค๊ณ„ ๋ฌธ์„œ ์ž‘์„ฑ ํ›„ stage
229
130
  git add workflow/REQ-2026-001/00-requirement.md workflow/REQ-2026-001/01-design.md workflow/REQ-2026-001/02-plan.md
230
- npm run req:review-codex -- 2026-001 --kind design --run
231
- ```
232
-
233
- - Codex๊ฐ€ ์„ค๊ณ„๋ฅผ ์ฝ๊ณ  **์Šน์ธ** ๋˜๋Š” **๋ณด์™„ ์š”์ฒญ(NEEDS_FIX)** ์„ ๋Œ๋ ค์ค๋‹ˆ๋‹ค.
234
- - ๋ณด์™„ ์š”์ฒญ์ด๋ฉด ์ง€์ ์‚ฌํ•ญ์„ ๋ฐ˜์˜ํ•˜๊ณ  **๋‹ค์‹œ `git add` โ†’ ์œ„ ๋ช…๋ น์„ ์žฌ์‹คํ–‰**ํ•˜์„ธ์š”. ์Šน์ธ๋  ๋•Œ๊นŒ์ง€ ๋ฐ˜๋ณตํ•ฉ๋‹ˆ๋‹ค.
235
-
236
- ### 4๋‹จ๊ณ„ โ€” ์ฝ”๋“œ ๊ตฌํ˜„ + ํ…Œ์ŠคํŠธ
237
131
 
238
- ์„ค๊ณ„๊ฐ€ ์Šน์ธ๋˜๋ฉด ์‹ค์ œ ์ฝ”๋“œ๋ฅผ ์งœ๊ณ  ํ…Œ์ŠคํŠธ๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค.
239
-
240
- ### 5๋‹จ๊ณ„ โ€” ๊ด€๋ฌธ ์ ๊ฒ€
132
+ # 3. ์„ค๊ณ„ ๋ฆฌ๋ทฐ
133
+ npm run req:review-codex -- 2026-001 --kind design --run
241
134
 
242
- ๋‚ด ๋ณ€๊ฒฝ์„ ๊ฒ€์‚ฌ๋Œ€์— ์˜ฌ๋ฆฌ๊ณ , ๊ฒŒ์ดํŠธ ์ƒํƒœ๋ฅผ ๋ฏธ๋ฆฌ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค:
135
+ # 4. ์ฝ”๋“œ ๊ตฌํ˜„ ํ›„ stage
136
+ git add <changed-source-files>
243
137
 
244
- ```sh
245
- git add <๋‚ด๊ฐ€-๋ฐ”๊พผ-์ฝ”๋“œ-ํŒŒ์ผ๋“ค>
138
+ # 5. ๊ฒŒ์ดํŠธ ์ ๊ฒ€
246
139
  npm run req:doctor -- 2026-001
247
- ```
248
-
249
- - ์—ฌ๋Ÿฌ ํ•ญ๋ชฉ(์„ค๊ณ„ ์Šน์ธ ์œ ํšจํ•œ์ง€, ๊ฒ€์‚ฌ๋Œ€์— ์˜ฌ๋ฆฐ ์ฝ”๋“œ์™€ ์Šน์ธ๋œ ์ฝ”๋“œ๊ฐ€ ๊ฐ™์€์ง€, ์›Œํ‚นํŠธ๋ฆฌ๊ฐ€ ๊นจ๋—ํ•œ์ง€ ๋“ฑ)์„ ์ ๊ฒ€ํ•ด **PASS/FAIL** ์„ ๋ณด์—ฌ์ค๋‹ˆ๋‹ค.
250
140
 
251
- > โš ๏ธ **์ค‘์š”:** `git add` ๋Š” **๋‹น์‹ ์ด ๋งŒ๋“  ์ฝ”๋“œ/๋ฌธ์„œ๋งŒ** ์˜ฌ๋ฆฌ์„ธ์š”. `state.json` ์ด๋‚˜ `responses/` ๊ฐ™์€ ์›Œํฌํ”Œ๋กœ ๋‚ด๋ถ€ ํŒŒ์ผ์€ **์˜ฌ๋ฆฌ์ง€ ๋งˆ์„ธ์š”.** (๋„๊ตฌ๊ฐ€ ์•Œ์•„์„œ ๊ด€๋ฆฌํ•ฉ๋‹ˆ๋‹ค. ์‹ค์ˆ˜๋กœ ์˜ฌ๋ฆฌ๋ฉด ์ปค๋ฐ‹ ๋‹จ๊ณ„์—์„œ ๋ง‰ํž™๋‹ˆ๋‹ค.)
252
-
253
- ### 6๋‹จ๊ณ„ โ€” ๊ตฌํ˜„ ๋ฆฌ๋ทฐ ๋ฐ›๊ธฐ (Codex)
254
-
255
- ```sh
141
+ # 6. ๊ตฌํ˜„ ๋ฆฌ๋ทฐ
256
142
  npm run req:review-codex -- 2026-001 --kind phase --run
143
+
144
+ # 7. ์Šน์ธ๋œ ์ฝ”๋“œ ์ปค๋ฐ‹
145
+ npm run req:commit -- 2026-001 --run -m "feat: my feature"
257
146
  ```
258
147
 
259
- - Codex๊ฐ€ **๊ตฌํ˜„ ์ฝ”๋“œ**๋ฅผ ๋ฆฌ๋ทฐํ•ฉ๋‹ˆ๋‹ค. ์—ญ์‹œ ์Šน์ธ๋  ๋•Œ๊นŒ์ง€ ๋ฐ˜์˜ โ†’ ์žฌ์‹คํ–‰ ๋ฐ˜๋ณต.
260
- - ์Šน์ธ๋˜๋ฉด `commit_allowed=true` ๊ฐ€ ๋˜์–ด ์ปค๋ฐ‹์ด ์—ด๋ฆฝ๋‹ˆ๋‹ค.
148
+ ์ค‘์š”: source ์ปค๋ฐ‹์—๋Š” ๋‚ด๊ฐ€ ๋งŒ๋“  ์ฝ”๋“œ์™€ ๋ฌธ์„œ๋งŒ stageํ•˜์„ธ์š”. `state.json`๊ณผ `responses/`๋Š” ๋„๊ตฌ๊ฐ€ ๊ด€๋ฆฌํ•ฉ๋‹ˆ๋‹ค.
261
149
 
262
- ### 7๋‹จ๊ณ„ โ€” ์ปค๋ฐ‹
150
+ ์—ฌ๋Ÿฌ ์ค„ ์ปค๋ฐ‹ ๋ฉ”์‹œ์ง€๋Š” `-m` ๋Œ€์‹  ํŒŒ์ผ์„ ์‚ฌ์šฉํ•˜์„ธ์š”.
263
151
 
264
152
  ```sh
265
- npm run req:commit -- 2026-001 --run -m "feat: my-feature ๊ตฌํ˜„"
153
+ npm run req:commit -- 2026-001 --run --message-file commit-message.txt
266
154
  ```
267
155
 
268
- - ๊ด€๋ฌธ(doctor ๊ฒŒ์ดํŠธ)์„ ๋งˆ์ง€๋ง‰์œผ๋กœ ํ†ต๊ณผํ•œ ๋’ค **์ฝ”๋“œ ์ปค๋ฐ‹ + ์ฆ๊ฑฐ ์ปค๋ฐ‹** ์„ ๋‚จ๊น๋‹ˆ๋‹ค.
269
- - ์Šน์ธ๋˜์ง€ ์•Š์•˜๊ฑฐ๋‚˜, ์Šน์ธ ํ›„ ์ฝ”๋“œ๊ฐ€ ๋ฐ”๋€Œ์—ˆ์œผ๋ฉด **์—ฌ๊ธฐ์„œ ๋ง‰ํž™๋‹ˆ๋‹ค.** (๊ทธ๊ฒŒ CommitGate์˜ ํ•ต์‹ฌ)
270
-
271
- ๐ŸŽ‰ ๋! ์ด์ œ ๋ฆฌ๋ทฐยท์Šน์ธยท์ฆ๊ฑฐ๊ฐ€ ๋ชจ๋‘ ๋‚จ์€ ์ƒํƒœ๋กœ ์•ˆ์ „ํ•˜๊ฒŒ ์ปค๋ฐ‹๋˜์—ˆ์Šต๋‹ˆ๋‹ค.
272
-
273
156
  ---
274
157
 
275
- ## ๐Ÿ“‹ ๋ช…๋ น์–ด ์น˜ํŠธ์‹œํŠธ
158
+ ## ๋ช…๋ น์–ด ์š”์•ฝ
276
159
 
277
- | ๋ช…๋ น | ํ•˜๋Š” ์ผ |
160
+ | ๋ช…๋ น | ์šฉ๋„ |
278
161
  |---|---|
279
- | `npx commitgate` | ํ”„๋กœ์ ํŠธ์— CommitGate ์„ค์น˜(์Šค์บํด๋”ฉ) |
280
- | `req:new <์ด๋ฆ„> --run` | ์ƒˆ ์ž‘์—… ํ‹ฐ์ผ“ + ๋ธŒ๋žœ์น˜ + ์„ค๊ณ„๋ฌธ์„œ ์ƒ์„ฑ |
281
- | `req:review-codex <๋ฒˆํ˜ธ> --kind design --run` | **์„ค๊ณ„** ๋ฆฌ๋ทฐ(Codex) |
282
- | `req:review-codex <๋ฒˆํ˜ธ> --kind phase --run` | **๊ตฌํ˜„** ๋ฆฌ๋ทฐ(Codex) |
283
- | `req:doctor <๋ฒˆํ˜ธ>` | ๊ด€๋ฌธ ์ ๊ฒ€(ํ†ต๊ณผ/์‹คํŒจ ํ‘œ์‹œ) |
284
- | `req:commit <๋ฒˆํ˜ธ> --run -m "๋ฉ”์‹œ์ง€"` | ์Šน์ธ๋œ ์ฝ”๋“œ ์ปค๋ฐ‹(+์ฆ๊ฑฐ) |
285
-
286
- > `-m "๋ฉ”์‹œ์ง€"` ๋Œ€์‹  ์—ฌ๋Ÿฌ ์ค„ ๋ฉ”์‹œ์ง€๋Š” `--message-file ๋ฉ”์‹œ์ง€.txt` ๋กœ ํŒŒ์ผ์—์„œ ์ฝ์„ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.
162
+ | `npx commitgate` | ํ”„๋กœ์ ํŠธ์— CommitGate ์„ค์น˜ |
163
+ | `req:new <slug> --run` | REQ ํ‹ฐ์ผ“, ๋ธŒ๋žœ์น˜, ์„ค๊ณ„๋ฌธ์„œ ์ƒ์„ฑ |
164
+ | `req:review-codex <id> --kind design --run` | ์„ค๊ณ„ ๋ฆฌ๋ทฐ |
165
+ | `req:review-codex <id> --kind phase --run` | ๊ตฌํ˜„ ๋ฆฌ๋ทฐ |
166
+ | `req:doctor <id>` | ๊ฒŒ์ดํŠธ ์ƒํƒœ ํ™•์ธ |
167
+ | `req:commit <id> --run -m "message"` | ์Šน์ธ๋œ ๋ณ€๊ฒฝ ์ปค๋ฐ‹ |
287
168
 
288
169
  ---
289
170
 
290
- ## โš™๏ธ ์„ค์ • (`req.config.json`, ์„ ํƒ)
171
+ ## ์„ค์ •
291
172
 
292
- ํ”„๋กœ์ ํŠธ ๋ฃจํŠธ์˜ `req.config.json` ์œผ๋กœ ๋™์ž‘์„ ๋ฐ”๊ฟ€ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. **ํŒŒ์ผ์ด ์—†์œผ๋ฉด ๊ธฐ๋ณธ๊ฐ’**์œผ๋กœ ์ž˜ ๋™์ž‘ํ•˜๋‹ˆ, ์ฒ˜์Œ์—” ์‹ ๊ฒฝ ์“ฐ์ง€ ์•Š์•„๋„ ๋ฉ๋‹ˆ๋‹ค.
173
+ ๋Œ€๋ถ€๋ถ„์€ ๊ธฐ๋ณธ๊ฐ’์œผ๋กœ ์ถฉ๋ถ„ํ•ฉ๋‹ˆ๋‹ค. ํ•„์š”ํ•˜๋ฉด ํ”„๋กœ์ ํŠธ ๋ฃจํŠธ์˜ `req.config.json`์„ ์ˆ˜์ •ํ•˜์„ธ์š”.
293
174
 
294
- | ํ•ญ๋ชฉ | ๊ธฐ๋ณธ๊ฐ’ | ๋œป |
175
+ | ํ•ญ๋ชฉ | ๊ธฐ๋ณธ๊ฐ’ | ์„ค๋ช… |
295
176
  |---|---|---|
296
- | `branchPrefix` | `"feat/req-"` | ์ƒˆ๋กœ ๋งŒ๋“œ๋Š” ๋ธŒ๋žœ์น˜ ์ด๋ฆ„ ์•ž๋ถ€๋ถ„ |
297
- | `ticketRoot` | `"workflow"` | ํ‹ฐ์ผ“ ํด๋” ์œ„์น˜ |
298
- | `packageManager` | ์ž๋™ ๊ฐ์ง€ | `npm` / `pnpm` / `yarn` |
299
- | `designDocs` | `00-/01-/02-*.md` | ์„ค๊ณ„๋ฌธ์„œ 3์ข… ํŒŒ์ผ๋ช… |
177
+ | `branchPrefix` | `"feat/req-"` | ์ƒˆ ๋ธŒ๋žœ์น˜ prefix |
178
+ | `ticketRoot` | `"workflow"` | REQ ํ‹ฐ์ผ“ ํด๋” |
179
+ | `packageManager` | ์ž๋™ ๊ฐ์ง€ | `npm`, `pnpm`, `yarn` |
180
+ | `designDocs` | `00/01/02` ๋ฌธ์„œ | ์„ค๊ณ„ ๋ฌธ์„œ ํŒŒ์ผ๋ช… |
300
181
 
301
- ์ž˜๋ชป๋œ ๊ฐ’(์˜ˆ: ๋นˆ `branchPrefix`, ํด๋” ๋ฐ–์œผ๋กœ ๋ฒ—์–ด๋‚˜๋Š” ๊ฒฝ๋กœ)์€ **์•ˆ์ „ํ•˜๊ฒŒ ๊ฑฐ๋ถ€**๋ฉ๋‹ˆ๋‹ค.
182
+ ๋นˆ `branchPrefix`๋‚˜ ํ”„๋กœ์ ํŠธ ๋ฐ–์œผ๋กœ ๋‚˜๊ฐ€๋Š” ๊ฒฝ๋กœ๋Š” ๊ฑฐ๋ถ€๋ฉ๋‹ˆ๋‹ค.
302
183
 
303
184
  ---
304
185
 
305
- ## โ“ ์ž์ฃผ ๋ฌป๋Š” ์งˆ๋ฌธ / ๋ฌธ์ œ ํ•ด๊ฒฐ
186
+ ## FAQ
306
187
 
307
- **Q. `codex` ๋ช…๋ น์ด ์—†๋‹ค๊ณ  ๋‚˜์™€์š”.**
308
- A. Reviewer(Codex CLI)๊ฐ€ ์„ค์น˜๋˜์–ด ์žˆ์–ด์•ผ ๋ฆฌ๋ทฐ๊ฐ€ ๋Œ์•„๊ฐ‘๋‹ˆ๋‹ค. ์„ค์น˜ ์ „์—๋Š” ๋ฆฌ๋ทฐ ๋ช…๋ น์ด "์กฐ์šฉํžˆ ํ†ต๊ณผ"ํ•˜์ง€ ์•Š๊ณ  **๋ช…ํ™•ํžˆ ์‹คํŒจ**ํ•ฉ๋‹ˆ๋‹ค โ€” ์ด๊ฒŒ ์ •์ƒ ๋™์ž‘(fail-closed)์ž…๋‹ˆ๋‹ค.
188
+ **Codex CLI๊ฐ€ ์—†์œผ๋ฉด ์–ด๋–ป๊ฒŒ ๋˜๋‚˜์š”?**
189
+ ๋ฆฌ๋ทฐ ๋ช…๋ น์ด ์‹คํŒจํ•ฉ๋‹ˆ๋‹ค. ์กฐ์šฉํžˆ ์Šน์ธ ์ฒ˜๋ฆฌํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค.
309
190
 
310
- **Q. ์ปค๋ฐ‹ ๋‹จ๊ณ„์—์„œ "staged tree != approved" ๊ฐ™์€ ์˜ค๋ฅ˜๊ฐ€ ๋‚˜์š”.**
311
- A. **์Šน์ธ๋ฐ›์€ ์ฝ”๋“œ์™€, ์ง€๊ธˆ ๊ฒ€์‚ฌ๋Œ€(git add)์— ์˜ฌ๋ฆฐ ์ฝ”๋“œ๊ฐ€ ๋‹ค๋ฅด๋‹ค**๋Š” ๋œป์ž…๋‹ˆ๋‹ค. ์Šน์ธ ํ›„์— ์ฝ”๋“œ๋ฅผ ๋ฐ”๊ฟจ๋‹ค๋ฉด 6๋‹จ๊ณ„(๊ตฌํ˜„ ๋ฆฌ๋ทฐ)๋ฅผ ๋‹ค์‹œ ๋ฐ›์•„ ์žฌ์Šน์ธํ•˜์„ธ์š”. (์Šน์ธ ๋ฐ”๊ฟ”์น˜๊ธฐ๋ฅผ ๋ง‰๋Š” ์•ˆ์ „์žฅ์น˜์ž…๋‹ˆ๋‹ค.)
191
+ **์Šน์ธ ํ›„ ์ฝ”๋“œ๋ฅผ ์กฐ๊ธˆ ๊ณ ์น˜๋ฉด ์ปค๋ฐ‹๋˜๋‚˜์š”?**
192
+ ์•ˆ ๋ฉ๋‹ˆ๋‹ค. ์Šน์ธ๋œ staged tree์™€ ๋‹ฌ๋ผ์ง€๋ฉด stale ์Šน์ธ์œผ๋กœ ๋ณด๊ณ  ๋‹ค์‹œ ๋ฆฌ๋ทฐ๋ฅผ ์š”๊ตฌํ•ฉ๋‹ˆ๋‹ค.
312
193
 
313
- **Q. "๋น„-์ฝ”๋“œ staged ๊ธˆ์ง€(state/responses)" ์˜ค๋ฅ˜๊ฐ€ ๋‚˜์š”.**
314
- A. `git add` ๋กœ `state.json` ์ด๋‚˜ `responses/` ๋ฅผ ์˜ฌ๋ ธ๊ธฐ ๋•Œ๋ฌธ์ž…๋‹ˆ๋‹ค. ๊ทธ ํŒŒ์ผ๋“ค์€ **์˜ฌ๋ฆฌ์ง€ ๋ง๊ณ **(๋„๊ตฌ๊ฐ€ ๊ด€๋ฆฌ), ๋‚ด๊ฐ€ ๋งŒ๋“  ์ฝ”๋“œ/๋ฌธ์„œ๋งŒ ์˜ฌ๋ฆฌ์„ธ์š”.
194
+ **`state.json`์ด๋‚˜ `responses/`๋Š” ์™œ stageํ•˜๋ฉด ์•ˆ ๋˜๋‚˜์š”?**
195
+ ์›Œํฌํ”Œ๋กœ ์ฆ๊ฑฐ์™€ ์ƒํƒœ ํŒŒ์ผ์ž…๋‹ˆ๋‹ค. source ์ปค๋ฐ‹์— ์„ž์ด๋ฉด ์Šน์ธ ๋ฐ”์ธ๋”ฉ์ด ํ๋ ค์ง€๋ฏ€๋กœ `req:commit`์ด ๋ง‰์Šต๋‹ˆ๋‹ค.
315
196
 
316
- **Q. `npx commitgate` ๋ฅผ ๋‘ ๋ฒˆ ์‹คํ–‰ํ•˜๋ฉด ๋ฎ์–ด์จ์ง€๋‚˜์š”?**
317
- A. ์•„๋‹ˆ์š”. **์ด๋ฏธ ์žˆ๋Š” ํŒŒ์ผ์€ ๊ฑด๋„ˆ๋œ๋‹ˆ๋‹ค**(๋ฉฑ๋“ฑ). ๊ฐ•์ œ๋กœ ๋ฎ์–ด์“ฐ๋ ค๋ฉด `--force` ๋ฅผ ๋ถ™์ด์„ธ์š”.
318
-
319
- **Q. Windows์ธ๋ฐ ์ปค๋ฐ‹ ๋ฉ”์‹œ์ง€ ์ค„๋ฐ”๊ฟˆ์ด ์ด์ƒํ•ด์š”.**
320
- A. ์—ฌ๋Ÿฌ ์ค„ ๋ฉ”์‹œ์ง€๋Š” `-m` ๋Œ€์‹  `--message-file ํŒŒ์ผ.txt` ๋ฅผ ์“ฐ๋ฉด ๊น”๋”ํ•ฉ๋‹ˆ๋‹ค.
197
+ **๋‘ ๋ฒˆ ์„ค์น˜ํ•˜๋ฉด ๋ฎ์–ด์“ฐ๋‚˜์š”?**
198
+ ์•„๋‹ˆ์š”. ๊ธฐ์กด ํŒŒ์ผ์€ ๊ฑด๋„ˆ๋œ๋‹ˆ๋‹ค. ๊ฐ•์ œ๋กœ ๊ฐฑ์‹ ํ•˜๋ ค๋ฉด `--force`๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”.
321
199
 
322
200
  ---
323
201
 
324
- ## ๐Ÿ”’ ์–ด๋–ป๊ฒŒ "์•ˆ์ „"์„ ๋ณด์žฅํ•˜๋‚˜์š”? (fail-closed)
202
+ ## ํ˜„์žฌ ๋ฒ”์œ„
325
203
 
326
- CommitGate์˜ ์›์น™์€ **"ํ™•์‹คํžˆ ์Šน์ธ๋์„ ๋•Œ๋งŒ ํ†ต๊ณผ, ์กฐ๊ธˆ์ด๋ผ๋„ ์• ๋งคํ•˜๋ฉด ๋ง‰๋Š”๋‹ค"** ์ž…๋‹ˆ๋‹ค.
204
+ ํ˜„์žฌ ๋ฒ„์ „์€ **Stage A: vendored scaffold ๋ชจ๋ธ**์ž…๋‹ˆ๋‹ค. ์ฆ‰ `npx commitgate`๊ฐ€ ๋Œ€์ƒ ํ”„๋กœ์ ํŠธ์— ์›Œํฌํ”Œ๋กœ ํŒŒ์ผ์„ ๋ณต์‚ฌํ•ฉ๋‹ˆ๋‹ค.
327
205
 
328
- - ์„ค๊ณ„๋ฌธ์„œ๊ฐ€ ์—†๊ฑฐ๋‚˜ ํ˜•์‹์ด ์•ˆ ๋งž์œผ๋ฉด โ†’ ๋ฏธ์Šน์ธ ์ทจ๊ธ‰
329
- - Codex๊ฐ€ ์„ค์น˜ ์•ˆ ๋จ / ๋ฆฌ๋ทฐ ์‹คํŒจ โ†’ ํ†ต๊ณผ ์•„๋‹˜, ๋ช…ํ™•ํžˆ ์‹คํŒจ
330
- - ์Šน์ธ๋œ ์ฝ”๋“œ ์ง€๋ฌธ๊ณผ ์ง€๊ธˆ ์ฝ”๋“œ๊ฐ€ ๋‹ค๋ฅด๋ฉด โ†’ ์ปค๋ฐ‹ ๊ฑฐ๋ถ€
331
- - ์›Œํ‚นํŠธ๋ฆฌ๊ฐ€ ์ง€์ €๋ถ„ํ•˜๋ฉด(๋ฆฌ๋ทฐ ์•ˆ ํ•œ ๋ณ€๊ฒฝ ์„ž์ž„) โ†’ ๋ฆฌ๋ทฐ/์ปค๋ฐ‹ ๊ฑฐ๋ถ€
206
+ ์•„๋ž˜๋Š” ํ›„์† ๋ฒ”์œ„์ž…๋‹ˆ๋‹ค.
332
207
 
333
- ์ฆ‰, **"๋ง‰ํžˆ๋Š” ๊ฒŒ ๊ธฐ๋ณธ, ํ†ต๊ณผ๊ฐ€ ์˜ˆ์™ธ"** ๋ผ ์‹ค์ˆ˜๋กœ ๋ฏธ๊ฒ€์ฆ ์ฝ”๋“œ๊ฐ€ ์ƒˆ์–ด ๋‚˜๊ฐˆ ํ‹ˆ์„ ์ค„์ž…๋‹ˆ๋‹ค.
208
+ - `node_modules`์—์„œ ์ง์ ‘ ์‹คํ–‰ํ•˜๋Š” ๋ผ์ด๋ธŒ๋Ÿฌ๋ฆฌ ๋ชจ๋ธ
209
+ - ๋น„-git VCS ์ง€์›
210
+ - ๋” ๋‹ค์–‘ํ•œ ์„ค๊ณ„๋ฌธ์„œ ํ…œํ”Œ๋ฆฟ
211
+ - Linux/macOS CI smoke ํ™•๋Œ€
334
212
 
335
213
  ---
336
214
 
337
- ## ๐Ÿ“„ ๋ผ์ด์„ ์Šค
215
+ ## License
338
216
 
339
217
  [MIT](./LICENSE) ยฉ 2026 sol5288
340
-
341
- > ์ด ์›Œํฌํ”Œ๋กœ๋Š” `palm-kiosk-app`์˜ REQ-2026-017 portability kit์—์„œ ๋…๋ฆฝ ํŒจํ‚ค์ง€๋กœ ์ถ”์ถœ๋˜์—ˆ๊ณ , **์ž๊ธฐ ์ž์‹ ์„ ์ด ์›Œํฌํ”Œ๋กœ๋กœ ๋ฆฌ๋ทฐยท์Šน์ธ(dogfood)** ํ•˜์—ฌ ๊ฒ€์ฆ๋˜์—ˆ์Šต๋‹ˆ๋‹ค.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "commitgate",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "CommitGate โ€” Builderโ†”Reviewer(Claudeโ†”Codex) fail-closed ์ปค๋ฐ‹ ๊ฒŒ์ดํŠธ: ๋ฆฌ๋ทฐยท์Šน์ธยท์ฆ๊ฑฐ ์—†์ธ ์ปค๋ฐ‹์„ ํ†ต๊ณผ์‹œํ‚ค์ง€ ์•Š๋Š” AI REQ ์›Œํฌํ”Œ๋กœ kit (req:new/review-codex/doctor/commit)",
5
5
  "type": "module",
6
6
  "license": "MIT",