Rename docs/decisions to docs/adr and add architecture vocabulary#431
Merged
Rename docs/decisions to docs/adr and add architecture vocabulary#431
Conversation
Align docs structure and terminology with the deepening / Ports & Adapters
vocabulary used by the improve-codebase-architecture skill.
- docs/decisions/ → docs/adr/ (matches skill convention; ADR is the wider
industry term and is what tooling expects)
- Renumber duplicate ADRs introduced by parallel branches:
0011-agui-sse-projection-session-pipeline → 0015 (lark-nyx kept 0011)
0012-studio-member-first-published-service → 0016 (channel-credential kept 0012)
- Update CLAUDE.md, repo README, tools/docs/lint.sh, tools/docs/build-index.sh,
test/tools/test_docs_tools.sh, plus in-doc cross-links in design / history /
ADR files.
- lint.sh now also rejects duplicate ADR numbers so the same collision can't
happen again.
- Add docs/canon/architecture-vocabulary.md mapping the skill's vocabulary
(Module / Interface / Depth / Seam / Adapter / Leverage / Locality) onto
aevatar's existing terms (Actor / GAgent / Port / ReadModel / Projection)
with anti-aliases for "boundary" / "service" / "API" / "component" so arch
reviews stay coherent.
- Regenerate docs/README.md.
Out of scope (follow-up): top-level CONTEXT.md / CONTEXT-MAP.md to satisfy
the skill's domain-language input — aevatar already uses docs/canon/ as a
multi-file context surface and a single-file CONTEXT redirect needs a
separate decision.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. @@ Coverage Diff @@
## dev #431 +/- ##
==========================================
- Coverage 70.50% 70.50% -0.01%
==========================================
Files 1198 1198
Lines 86188 86188
Branches 11297 11297
==========================================
- Hits 60771 60766 -5
- Misses 21032 21036 +4
- Partials 4385 4386 +1
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
eanzhao
commented
Apr 27, 2026
Contributor
Author
eanzhao
left a comment
eanzhao
left a comment
There was a problem hiding this comment.
术语和文档规范这条线整体方向是对的。我留了 3 个改进点，主要集中在 docs tooling 的可验证性和一处术语歧义。
| } | ||
| for file in "$DOCS_DIR"/canon/*.md; do [ -f "$file" ] && check_frontmatter "$file"; done 2>/dev/null | ||
| for file in "$DOCS_DIR"/decisions/*.md; do [ -f "$file" ] && check_frontmatter "$file"; done 2>/dev/null | ||
| for file in "$DOCS_DIR"/adr/*.md; do [ -f "$file" ] && check_frontmatter "$file"; done 2>/dev/null |
Contributor
Author
There was a problem hiding this comment.
P2: 这里仍然是测试里复制了一份简化版 lint 逻辑，而不是调用真实的 tools/docs/lint.sh。这会导致本 PR 新增的 ADR 编号唯一性规则没有测试覆盖。建议让 lint.sh 支持 DOCS_DIR override，测试直接调用真实脚本，并增加重复 0017-* 文件应失败的用例。
| if [ -d "$DOCS_DIR/decisions" ]; then | ||
| for file in "$DOCS_DIR"/decisions/*.md; do | ||
| # Check ADR file naming: must start with NNNN- and numbers must be unique | ||
| if [ -d "$DOCS_DIR/adr" ]; then |
Contributor
Author
There was a problem hiding this comment.
P2: rename 到 docs/adr/ 后，lint 只扫描新目录。如果后续旧分支又带回 docs/decisions/*.md，当前门禁会直接忽略它。建议显式检查 docs/decisions 是否存在，存在就失败并提示用 git mv 迁到 docs/adr。
| - 描述结构（"这个 module 太 shallow，应该 deepen 进 GAgent"）→ 用本表词汇。 | ||
| 2. ADR 的 Context 段落用本表词汇描述当前结构问题；Decision 段落仍可使用领域语言落地。 | ||
| 3. **不要混用**：同一段话里"边界"和"seam"含义清晰可分；但"boundary 边界"如果用来指可替换位置就是错的，应该改成"port"或"seam"。 | ||
| 4. 中文写作时优先用括号显式给出英文术语：例如"接缝（seam）"、"深度（depth）"、"接缝（port）"，避免"边界"被随意替代。 |
Contributor
Author
There was a problem hiding this comment.
P3: 这里的“接缝（port）”容易把 seam 和 port 直接等同。建议改成“接缝（seam）/ 端口（port）”：seam 是概念，port 是 Aevatar 中常见的落地形态。
- vocabulary: split "接缝（seam）/ 端口（port）" so seam (concept) and port (aevatar landing form) are not aliased. - lint.sh: reject legacy docs/decisions/ directory with a git-mv hint, so branches that re-introduce the old path fail the gate instead of being silently ignored. - lint.sh + build-index.sh: honour DOCS_DIR env override so tests can drive the real scripts instead of an in-test reimplementation. - test_docs_tools.sh: invoke the real tools/docs/lint.sh via DOCS_DIR; add cases for unique ADR numbers (passes), duplicate ADR numbers (fails), missing NNNN- prefix (fails), legacy docs/decisions/ present (fails), and canonical date-prefix rejection. Build-index test now drives the real script as well. 12/12 pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
eanzhao
commented
Apr 27, 2026
Contributor
Author
eanzhao
left a comment
eanzhao
left a comment
There was a problem hiding this comment.
复查 d83f449：前面 3 条 review 都已覆盖。lint.sh / build-index.sh 现在支持 DOCS_DIR override，test_docs_tools.sh 已改成调用真实脚本并覆盖重复 ADR 编号、旧 docs/decisions/ 回归、ADR 前缀、canon 日期前缀等用例；术语文档也已把 seam 和 port 拆开。
本地验证通过：
git diff --check origin/dev...HEADbash tools/docs/lint.shbash test/tools/test_docs_tools.shbash tools/docs/build-index.sh && git diff --exit-code -- docs/README.mdbash tools/ci/test_stability_guards.sh
当前没有新增 findings；GitHub checks 还有若干 pending，可以等 CI 完整跑完。
…d-deepening-vocab
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Align docs structure and terminology with the deepening / Ports & Adapters vocabulary used by the
improve-codebase-architectureskill.docs/decisions/→docs/adr/. ADR is the wider industry term and what external tooling expects. All 14 ADRs moved withgit mv(history preserved); CLAUDE.md / repo README /tools/docs/lint.sh/tools/docs/build-index.sh/test/tools/test_docs_tools.sh/ in-doc cross-links updated;docs/README.mdregenerated.0011-agui-sse-projection-session-pipeline→0015(the lark-nyx ADR keeps 0011, since it landed first at 2026-04-22 10:13).0012-studio-member-first-published-service→0016(channel-credential keeps 0012, landed 2026-04-22 16:19; studio came in 2026-04-23 15:54).# ADR-NNNN:headings + cross-links indocs/design/anddocs/history/updated.tools/docs/lint.shnow rejects duplicate ADR numbers so this collision can't recur silently.docs/canon/architecture-vocabulary.mdmapping the skill's vocabulary (Module / Interface / Depth / Seam / Adapter / Leverage / Locality) onto aevatar's existing terms (Actor / GAgent / Port / ReadModel / Projection), with anti-aliases forboundary/service/API/componentso arch reviews stay coherent. CLAUDE.md## 文档系统now references it.Out of scope (follow-up)
CONTEXT.md/CONTEXT-MAP.mdfor the skill's domain-language input. Aevatar already usesdocs/canon/as a multi-file context surface; whether to also add a single-file redirect needs a separate decision.Test plan
bash tools/docs/lint.sh→PASSED — 30 file(s) checked, 0 errorsbash tools/docs/build-index.sh→ regeneratesdocs/README.mdwithadr/paths and the new canon docbash test/tools/test_docs_tools.sh→ 7 passed, 0 failedgrep -r "docs/decisions" .→ no matches in tracked content🤖 Generated with Claude Code