Fiery Clouds’s Blog

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). ...

Many projects start with just one database. So AI naturally writes: async def get_user(user_id: int): async with sqlite_session() as session: ... Or even more directly: conn = sqlite3.connect("app.db") The feature certainly works, but problems will show up later. Today it’s SQLite, tomorrow it might need to switch to PostgreSQL … As the codebase grows, the project quickly becomes: Business code tightly coupled to a specific storage technology. This is exactly the problem that Multi-Data-Source Architecture aims to solve. ...

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 real-world development, we often need to use multiple Git accounts on the same computer, for example: Personal GitHub account Company GitHub account GitLab account Gitee account If you simply use the default Git configuration, you can easily run into these problems: Using the wrong account when running git push Commit history showing up under a different account Not knowing which SSH Key to use Frequently modifying user.name and user.email across different projects SSH configurations for GitHub, GitLab, and other platforms interfering with each other The most stable solution to these problems is: One account per SSH Key, distinguish accounts through SSH Config, and determine commit identity through project-level Git Config. Below, using Windows as an example, we’ll build a complete Git multi-account workflow. ...

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). ...