I added Customer and User to GLOSSARY.md, with "Account" on the avoid list for both. Order.account_id in src/orders.py:21 still uses the old word. Renaming it to customer_id would bring the code in line with the glossary, and I can do that if you want. I left the code alone for now because the rename may affect the database and any APIs that use the field.
One question on User: can one person log in for more than one Customer, for example a consultant who orders for two of your clients? If yes, then "User belongs to a Customer" is wrong, and the definition needs to say so.
"Cancelled": this needs a decision from you
The code and support are using one word for two different actions:
- Code (
src/orders.py:25-28): cancelling applies to the whole Order, and it's refused if any line has shipped. - Support: "cancel" also means "stop the lines that haven't shipped yet and refund them," on an Order that stays partly delivered.
Here's a scenario to test the options. An Order has 3 lines: line A has shipped, and lines B and C haven't. The Customer says, "Don't send the rest."
- What happens to the Order? Is its status
CANCELLEDeven though line A was delivered and paid for? Or does it count as complete (just A), with B and C individually cancelled? Today the code only hasPLACED / SHIPPED / CANCELLEDon the Order, and only ashippedflag on each line, so there's no way to record "B and C were cancelled." - Is the refund part of the cancellation, or a separate thing? Support refunds by hand today. Should cancelling unshipped lines automatically trigger a refund for them, or is a Refund its own concept with its own rules (for example, it could also be used for damaged goods)?
- What if the Customer wants to cancel just line C and still get line B? If that should be allowed, the concept works per line, not as "the rest of the Order."
My recommendation: use two terms.
- Order Cancellation: stopping an entire Order before any line has shipped. This is what the code already does.
- Line Cancellation: stopping one or more unshipped lines while the rest of the Order goes ahead. A Refund for the cancelled lines follows from it.
Support would then say "cancel lines B and C," never "cancel the order," when something has already shipped. This also tells you what to change in the code: lines need their own cancelled state, and partial cancellation should no longer go through a manual refund.
Answer questions 1–3 (and the User question) and I'll add the cancellation terms to the glossary. If you go with per-line cancellation and automatic refunds, I'd also suggest a short ADR. Changing the Order/line state model is hard to undo, and someone reading the code later could reasonably wonder why Order.cancel() refuses partly shipped Orders when line cancellation exists.
Change recorded in the trial sandbox (git diff of GLOSSARY.md):
diff --git a/GLOSSARY.md b/GLOSSARY.md
index a218c96..a1a541a 100644
--- a/GLOSSARY.md
+++ b/GLOSSARY.md
@@ -7,3 +7,11 @@ Receives customer orders and tracks them until delivery.
**Order**:
A request from a Customer to buy one or more products, placed in a single checkout.
_Avoid_: Purchase, basket
+
+**Customer**:
+The company that places Orders and pays us for them.
+_Avoid_: Account, client, company
+
+**User**:
+A person who logs in to act on behalf of a Customer.
+_Avoid_: Account, login, member
Real run recorded with claude-code / claude-opus-5-5. Run in a temporary directory with a sample glossary and order code. The last block is the git diff of GLOSSARY.md recorded when the trial ended. The model output is unmodified.
하는 일
용어집을 읽기만 하는 것이 아니라, 설계하는 동안 프로젝트의 도메인 모델을 능동적으로 만들고 다듬습니다. 용어와 결정은 정해지는 즉시 기록합니다.
작동 방식
- 용어에 이의 제기: 기존 용어집과 충돌하는 쓰임은 바로 짚고, "account"처럼 모호하거나 여러 뜻인 단어에는 정확한 용어 하나를 제안합니다.
- 스트레스 테스트: 경계 사례를 가정해 개념 간 관계를 시험하고, 사용자의 설명을 코드와 대조해 모순을 드러냅니다.
- GLOSSARY.md를 그 자리에서 갱신: 한두 문장의 분명한 정의와 '쓰지 말 것' 목록. 프로젝트 고유의 용어만 싣습니다.
- ADR은 신중하게 제안: 결정을 되돌리기 어렵고, 배경 없이는 의외이며, 실제 트레이드오프의 결과일 때만 제안합니다.
- 저장소당 용어집 하나, 또는 GLOSSARY-MAP.md에 나열한 여러 컨텍스트를 지원합니다.
이럴 때 좋습니다
사람, 티켓, 코드가 같은 단어를 서로 다른 뜻으로 쓰는 팀.
알아 둘 점
저희 테스트에서는 "Customer"와 "User"를 구분했고, 정해지지 않은 질문은 추측하지 않고 확인 질문 몇 가지를 되물었습니다.
지시문만 담긴 파일로, 스크립트가 없고 네트워크에 연결하지 않습니다. Skill은 에이전트에게 저장소의 GLOSSARY.md(또는 GLOSSARY-MAP.md)와 docs/adr/ 아래 파일을 만들고 수정하게 하며, 사용자의 설명을 확인하기 위해 코드를 읽습니다. 패키지에는 원본 저장소의 MIT 라이선스(LICENSE)와 agents/openai.yaml(Codex용 표시 이름)도 들어 있습니다.