docs(readme): refresh opening, add Features + Status, sharpen comparison#96
Merged
Conversation
Address the "thin README" feedback by: - Open with a problem statement (5-file split) instead of jumping straight to mermaid - Add a Features section with 5 differentiated bullets pulled from feature-highlights.md - Make the N+1 pitch concrete (100 users × 10 posts → still 2 queries, not 101) - Expand comparison table with 2 more dimensions (SQL pruning, multi-transport) and replace glib "manual" cells with specific costs - Add a paragraph crediting Strawberry / FastMCP where they shine, framing nexusx as a tradeoff - Add Status section so readers know it's alpha before adopting Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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
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
README 感觉有点单薄,这版按之前讨论的优先级做了 5 处补强(截图那条留作后续——需要先跑 demo)。
改动
开篇加问题陈述:原 hero 后直接跳到 mermaid 图,读者不知道在解决什么痛点。补一段"传统全栈要把一个 domain 拆成 5 份文件",把"manual"的含义提前讲清楚。
新增 Features 区块:从
docs/feature-highlights.md抽 5 条最锋利的差异化点(N+1 自动消除 / 选择贯穿全栈 / 超越 ORM 的关系 / 一种 service 多传输 / AI-agent-first MCP),README 之前完全没有体现这块。Quick Start Step 1 给具体 N+1 数字:原来只说"恰好两次 SQL 往返",没有规模感。补一句"100 个 user × 各 10 篇 post,仍然是 2 次查询,不是 101 次"——一句数字胜过对勾。
Comparison table 扩充 + 公平评价:
新增 Status 区块:PyPI 已经标了
Development Status :: 3 - Alpha,README 之前完全没说采用风险。一句话让读者知道是 alpha,API 可能变。没做的
Test plan
🤖 Generated with Claude Code