AI handles the “speed,” humans handle the “blueprints.” This column outlines common software architecture design techniques, aiming to teach you how to tame AI to write industrial-grade, highly maintainable, high-quality code through “architectural design” and “rule constraints (Prompt / Rules),” avoiding the pitfall of “the more code you write, the faster the system crashes.” ...
In this series, we have discussed a range of engineering practices: frontend-backend separation, DDD (Domain-Driven Design), layered architecture, DI (Dependency Injection), RESTful (Representational State Transfer), async & concurrency, SSE (Server-Sent Events), plugin architecture, and Project Rules. It may look like a lot of technology, but they all ultimately point to the same question: Now that AI can generate large amounts of code, what is still the most important capability for a programmer? The answer is shifting from: “How to write the code” to: “How to design a system in which AI can write code correctly.” ...
AI writes code fast, but it is also prone to a typical problem: Every time a feature is added, more if/elif branches pile into the core code. For example: if domain == "legal": ... elif domain == "finance": ... elif domain == "medical": ... With few features this is fine, but as the types keep growing, the core module becomes increasingly bloated, and every new feature risks affecting existing logic. A more reasonable approach is to define upfront: Plugin Extension Point And let AI follow one principle: New capabilities should preferably be added as new modules, not by modifying the core flow. ...
In web systems, there is a type of requirement that is especially prone to being implemented by AI as “it runs, but it’s dumb”: Frontend: Ask the server every 1 second "Is the task done?" Server: "No." Ask again 1 second later: "Is it done?" This approach is called: Polling Querying a status occasionally is fine, but for real-time scenarios such as AI streaming responses, OCR progress, document parsing, knowledge base construction, and background task status, high-frequency polling generates a large number of useless requests. A more appropriate solution is usually: SSE (Server-Sent Events) Or: WebSocket — a full-duplex, long-lived connection protocol The core idea boils down to one sentence: Don’t make the client keep asking “Got any message yet?” — let the server push messages proactively when there is something new. ...
There is a very common problem with AI-generated code: The code runs, but slows down as soon as multiple users access it. Especially in Python Web projects, even when using FastAPI and functions are written as async def, operations such as database queries, HTTP requests, and large language model (LLM) calls may still block synchronously. The key issue is: async def is merely the entry point of an asynchronous function — it does not automatically turn the synchronous code inside it into asynchronous code. For systems that heavily rely on external I/O — such as web services, knowledge bases, and agent platforms — establishing a unified async and concurrency architecture is an important foundation for improving system throughput. ...
AI (Artificial Intelligence) has a very common problem when writing code: It loves to “hardcode things on a whim.” timeout = 30 max_retries = 3 model = "qwen3:14b" raise ValueError("User does not exist") Individually, there’s nothing fundamentally wrong with any of these lines. But when dozens of modules each have their own 30, 3, model names, and prompt text, maintainers start getting headaches: What do these values mean? Where should they be changed? What happens when switching environments? How do we support English? Therefore, AI programming projects should establish a clear architectural rule upfront: Values with business significance, environment-specific differences, or user-visible meaning are not allowed to be scattered across business code. This problem is primarily addressed through two mechanisms: Centralized Configuration + I18n (Internationalization). ...
When AI writes business code, it has a very typical tendency: async def get_user(user_id: int): return await user_db.get_by_id(user_id) Functionally correct. But if every read in the project becomes: Read user → Database Read permissions → Database Read model → Database Read Agent → Database Read knowledge base → Database Read config → Database The system soon enters a state where: Every function is correct, yet the overall architecture grows increasingly inefficient. The problem is not merely “whether there is a cache”, but: The AI never first asks: what I want to reuse — a “value”, or an “already-built runtime object”? This is exactly what’s most worth borrowing from miniagent’s current caching architecture. It doesn’t just build one cache — it explicitly splits into two categories: Object Cache Object caching Value Cache Value caching These two solve fundamentally different problems. ...
In AI programming, there is one category of code that easily “grows and grows messier”: if user.role != "admin": raise HTTPException(status_code=403) Switch to another endpoint, and the AI writes: if "user:delete" not in user.permissions: raise ForbiddenError() Yet another endpoint: if current_user.id != owner_id and not current_user.is_admin: raise HTTPException(status_code=403) Each snippet looks defensible on its own. But once dozens of variations of these ifs appear across the project, the permission system has effectively gone out of control. The mature solution is not “make the AI write its if-statements more carefully”, but to establish a unified: Authentication + permission model + permission enforcement mechanism The most common permission model here is RBAC (Role-Based Access Control). ...
In the age of AI programming, there is one kind of code that gets copied around with abandon: logger.info("Start processing request") if not token: raise UnauthorizedError() start = time.time() result = await service.do_something() logger.info(f"Execution time: {time.time() - start}") return result At first there is only one endpoint, and it looks harmless enough. But once the project grows to dozens or even hundreds of endpoints, things quickly become: User endpoints ├─ Authentication ├─ Logging ├─ Parameter validation ├─ Business logic └─ Instrumentation Agent endpoints ├─ Authentication ├─ Logging ├─ Parameter validation ├─ Business logic └─ Instrumentation Knowledge base endpoints ├─ Authentication ├─ Logging ├─ Parameter validation ├─ Business logic └─ Instrumentation ... The only truly different part is the few lines of business logic in the middle. As for the rest, every time the AI writes another endpoint, it dutifully copies it all over again. This is exactly the problem that AOP (Aspect-Oriented Programming) set out to solve. ...
Define the API rules clearly first, then let AI write the code. In AI-assisted development, interface design is an area that easily “looks like it works, but gets increasingly messy over time.” Ask AI to write a few APIs for you, and it might quickly generate: /getUser /createUser /update_user /delete-user /userList They all work functionally. But as the project continues to grow, you easily end up with: Same resource, different naming Same action, different HTTP methods Same error, different response structures Same pagination, different field names Eventually, frontend developers, backend developers, testers, and even AI itself start guessing: “How exactly should this API be called?” What’s truly missing here is not coding ability, but: A unified API contract. ...