四年之久的拼写错误，没人能修复 🧟，以及更多关于构建开发者工具的内容

Source: Dev.to

作为 Making Software 的主持人，我有机会进行一些非常真实的对话，探讨真正构建优秀软件所需的条件。在最近一次与 Raghd Hamzeh（Okta 高级软件工程师、OpenFGA 核心维护者）的聊天中，我们深入探讨了工程领域中鲜少被提及的一个侧面：当你的用户是其他工程师时会发生什么？如果你曾经构建过 API、SDK，甚至只是一个共享库，你就会知道开发者是最有回报感——也是最“爱发声”的受众。

1. “Breaking Change” 痒点真的存在 😬

Raghd 承认了我们很多人都能感同身受的事：一个四年前的拼写错误会让你抓狂。它可能只是一个微小的命名不一致，但一旦出现，它每次出现时都会盯着你。

我们都知道每个维护者内部的斗争：是为了保持 API 的整洁而破坏所有人的构建吗？答案大概是否定的。这提醒我们，第一月做出的决定——比如参数的传递方式——会成为你在第五年仍需共存的遗留。

2. 停止构建 “外星” SDK 👽

在为 OpenFGA 编写 Ruby SDK 时，我正面碰到了这个问题。Ruby 开发者是有主见的（我深有体会，因为我也是其中一员）。

在构建多语言工具时，你必须不断平衡两件事：

• 一致性： 确保 Go SDK 与 Python SDK 的行为保持一致。
• 惯用性： 确保 Ruby 开发者不会觉得自己在写带有额外步骤的 Java 代码。

Raghd 的观点是？你不可能在每一次都做到 100% 完美。有时你必须把平台的长期健康置于“完美惯用实现”之上，这样项目才能对背后的团队保持可维护性。这种张力永远不会完全消失——只会让你在其中游刃有余。

3. 实际为人类准备的 “AI” 文件 🤖

随着 AI 的兴起，许多仓库现在都包含 agents.md 文件。Raghd 给出了一个辣味建议：先为你的人工贡献者编写该文件。

如果你想让人们帮助你实现开源梦想，就要清晰地列出你的期望：

• 提交记录应如何组织？
• 核心架构是什么样的？
• 贡献者在提交 PR 之前是否需要先打开 Issue？

提前记录这些“非代码”决策可以节省大量摩擦。它把 “这个 PR 不是我们想要的” 变成 “这是我们大家遵循的蓝图”。

完整节目

在此查看 Making Software 的完整节目： Link to episode