夜雨聆风Designing AI-First .NET Systems: How to Build Codebases That Work With AI, Not Against It
设计以人工智能为先的.NET 系统：如何构建与 AI 协作而非对抗的代码库
Practical patterns to structure .NET projects so Claude and other AI tools actually become effective teammates
实用的模式，帮助构建.NET 项目，使 Claude 和其他 AI 工具真正成为高效的团队成员
AI tools like Claude are powerful.像 Claude 这样的 AI 工具非常强大。
But if we have tried using them inside real .NET projects, we might have noticed something strange.但如果我们尝试在真实的.NET 项目中使用它们，可能会发现一些奇怪的地方。
In some codebases, AI feels incredibly helpful.在某些代码库中，AI 感觉非常有帮助。In others, it becomes confusing, inconsistent, and sometimes completely wrong.在其他情况下，这会变得令人困惑、不一致，有时甚至完全错误。
The difference is not the AI.区别不在于 AI。
It is how we design the codebase.这就是我们设计代码库的方式。
The Problem Most Developers Miss大多数开发者忽视的问题
Most teams are doing this:大多数队伍都在这样做：
Adding AI tools on top of existing projects在现有项目基础上添加 AI 工具 Expecting better productivity instantly期待立刻提升生产力
But many codebases are:但许多代码库是：
inconsistent不一致 tightly coupled紧密耦合 poorly structured结构糟糕
This creates a hidden problem:这带来了一个隐藏的问题：
AI cannot reason well in messy systems人工智能在混乱的系统中推理能力不强
When the structure is unclear, AI:当结构不明确时，人工智能：
makes wrong assumptions做出错误的假设 introduces incorrect patterns引入错误的模式 produces inconsistent code生成的代码不一致
What Makes a Codebase AI-Friendly什么让代码库对 AI 友好
To make AI useful, our codebase needs to be predictable.为了让人工智能有用，我们的代码库需要是可预测的。
Here are the core traits.以下是核心特质。
1. Clear Structure1. 清晰的结构
AI performs better when our project has:当我们的项目具备以下条件时，AI 表现会更好：
well-defined layers明确定义层 clear folder organization清晰文件夹组织 consistent naming统一命名
Example:示例：
Application/Domain/Infrastructure/API/This reduces ambiguity.这减少了歧义。
2. Small, Focused Methods2. 小而聚焦的方法
AI struggles with large methods.人工智能在处理大型方法时遇到困难。
Bad example:举个不好的例子：
publicasync Task ProcessOrder(){// 200 lines of mixed logic}Better:更好：
publicasync Task ProcessOrder(){ ValidateOrder(); CalculateTotal(); SaveOrder();}Now AI can:现在人工智能可以：
understand intent理解意图 modify safely安全修改 suggest improvements提出改进建议
3. Explicit Contracts3. 明确契约
Avoid ambiguity.避免模糊不清。
Use:用途：
clear DTOs清除 DTO well-defined interfaces定义良好的接口 predictable method signatures可预测的方法签名
Example:示例：
publicclassCreateOrderRequest{publicint CustomerId { get; set; }public List<OrderItemDto> Items { get; set; }}This improves AI accuracy significantly.这显著提升了 AI 的准确性。
Designing for AI in .NET在.NET 中为人工智能设计
Let’s make this practical.让我们把这变成现实点。
Use Consistent Patterns使用一致的模式
If one service uses a pattern, all should.如果一个服务使用模式，所有服务都应该使用。
Bad:缺点：
different naming conventions不同的命名规则 mixed architectures混合架构 inconsistent dependency injection不一致依赖注入
Good:好：
predictable structure across services跨服务的可预测结构
AI learns from patterns. Consistency improves output.人工智能会从模式中学习。一致性能提升产出。
Keep Services Small保持服务规模
Instead of:而不是：
OrderService (handles everything)Split into:分为：
OrderServicePaymentServiceNotificationServiceThis makes reasoning easier for both humans and AI.这使得人类和人工智能的推理都更容易。
Avoid Hidden Logic避免隐藏逻辑
Do not bury logic in:不要把逻辑埋藏在：
extensions扩展 deeply nested conditions深层嵌套条件 implicit behavior隐性行为
AI struggles with implicit flows.人工智能在隐性流动方面遇到困难。
Prefer Readability Over Clever Code更注重可读性胜过巧妙的代码
Avoid:避免：
overly compact LINQ过紧 LINQ complex one-liners复杂的单句话
Prefer:偏好：
simple, readable logic简单易读的逻辑
This improves both maintainability and AI assistance.这不仅提升了可维护性，也提升了人工智能辅助。
CLAUDE.md as a System ContractCLAUDE.md 作为系统合同
Most developers treat CLAUDE.md as documentation.大多数开发者把 CLAUDE.md 当作文档。
That is a mistake.这是个错误。
It is actually a contract between our codebase and the AI.这实际上是我们代码库与 AI 之间的合同。
A good CLAUDE.md should include:一个好的 CLAUDE.md 应包括：
architecture rules架构规则 naming conventions命名规则 do and don’t guidelines做与不做的指导原则 preferred patterns首选模式
But remember:但请记住：
It only works if our codebase follows those rules consistently.只有当我们的代码库始终遵循这些规则时，它才有效。
Before vs After: Real Difference前后：真正的差别
Let’s look at a simplified example.让我们来看一个简化的例子。
Before (Messy Code)之前（混乱代码）
publicasync Task Handle(int id){var data = await _repo.Get(id);if (data != null) {if (data.IsActive) {if (data.Amount > 1000) {// multiple nested logic } } }}AI struggles here.AI 在这里很挣扎。
After (AI-Friendly)之后（对 AI 友好）
publicasync Task Handle(int id){var data = await GetValidData(id);if (!IsEligible(data))return;await ProcessHighValueOrder(data);}Now AI can:现在人工智能可以：
extend logic safely安全扩展逻辑 refactor confidently信心重构 suggest improvements提出改进建议
Prompting Changes When Code Improves代码改进时的提示更改
Something interesting happens when our code improves.当我们的代码改进时，会发生一些有趣的事情。
We need fewer instructions.我们需要更少的指令。
Instead of:而不是：
Act as a senior developer. Follow clean architecture. Avoid over-engineering.作为高级开发者。遵循干净的建筑风格。避免过度设计。
We can simply say:我们可以简单地说：
Extend this feature with validation.通过验证扩展此功能。
Because the structure already guides the AI.因为结构已经引导着 AI。
The Bigger Shift更大的转变
We are entering a new phase of software development.我们正进入软件开发的新阶段。
We are no longer writing code only for humans.我们不再只是为人类编写代码。
We are writing code for humans and AI.我们正在为人类和人工智能编写代码。
This changes priorities:这改变了优先级：
Clarity becomes critical清晰变得至关重要 consistency becomes essential一致性变得至关重要 simplicity becomes powerful简单变得强大
What This Means for Developers这对开发者意味着什么
The best developers will not just use AI tools.最优秀的开发者不会只用 AI 工具。
They will:他们将：
design AI-friendly systems设计对 AI 友好的系统 enforce consistency强制一致性 reduce ambiguity减少歧义
This is a new skill.这是一项新技能。
And it will matter more over time.而且随着时间推移，这会更加重要。
Final Thoughts总结
AI does not magically fix bad systems.人工智能不会神奇地修复糟糕的系统。
It amplifies what already exists.它放大了已有的存在。
If our codebase is:如果我们的代码库是：
clean干净 structured结构化 consistent一致性
AI becomes a powerful teammate.AI 成为强大的队友。
If not, it becomes a source of confusion.如果不是，就会造成混乱。
The future is not just AI-assisted development.未来不仅仅是人工智能辅助开发。
It is an AI-aware system design.它是一种人工智能感知系统设计 。
☕ Support the Author☕ 支持作者
If you found this useful, consider supporting the work:
长按关注：HackerVirus
