Introduction
Set up architecture and automation systems early, let AI run efficiently on safe tracks
Quick Start
In the previous chapter, we completed technology selection. Now itโs time to initialize your project or optimize your existing project structure.
New Projects: Use Scaffolds
If youโre starting from scratch, we recommend these battle-tested starter templates:
| Tech Stack | Recommended Scaffold | Features |
|---|---|---|
| React/Next.js | shadcn/uiย | Modern UI components, native TypeScript support |
| Next.js Enterprise | next-enterpriseย | Enterprise-grade architecture with complete toolchain |
| Spring Boot | spring-boot-boilerplateย | Production-ready backend template |
Existing Projects: Optimize
If you already have a project, you can directly apply the practices in this chapter:
- Project structure optimization: Reorganize directories, split large files
- Toolchain configuration: Introduce static analysis, testing, CI/CD
Core Concept: Architecture First
In the era of AI-assisted development, many believe they can let AI โfreely exploreโ to build systems. However, practice has shown that without a solid engineering foundation, AI tends to introduce deviations, technical debt, or low-quality output.
The Restaurant Analogy
| Restaurant Element | Software Architecture | Whoโs Responsible |
|---|---|---|
| ๐๏ธ Kitchen Layout | System architecture, directory structure | Humans must carefully plan |
| ๐ Menu Design | API design, interface contracts | Humans define contracts |
| ๐ณ Cooking Process | Business logic implementation | AI implements efficiently |
| ๐ Health Inspection | Static analysis, testing | Tools provide automatic feedback |
Just as an excellent executive chef must first design the kitchen layout and workflow to enable the culinary team to operate efficiently, humans must manually establish a solid architectural foundation at the beginning of the project.
Automation Tool Layering
When introducing automation tools, the key is to identify which tools are suitable for the AI workflow and which should remain in automated/manual processes.
๐ค Tools in AI Workflow
These tools should be integrated into AIโs work loop, providing instant feedback:
| Tool Type | Examples | How AI Uses It |
|---|---|---|
| Type Checking | TypeScript, mypy | AI checks type errors immediately after generating code |
| Linter | ESLint, Ruff | AI auto-fixes code style based on lint errors |
| Unit Testing | Vitest, PyTest | AI runs tests to verify functionality |
| Formatting | Prettier, Black | AI auto-formats output code |
Principle: Donโt add too many tools to the AI workflow. Each additional tool increases AIโs cognitive load and execution time. Keep only core tools that provide deterministic feedback.
โ๏ธ Tools in Automated Processes
These tools should run in automated processes, not in the AI workflow:
| Tool Type | Examples | Trigger Timing |
|---|---|---|
| Pre-commit Hook | husky + lint-staged | When developer commits code |
| Pre-push Hook | Full test suite | Before pushing code |
| CI Checks | GitHub Actions | When PR is created/updated |
| Security Scanning | Dependabot, Snyk | Periodically or on PR |
๐งโ๐ป Tools in Manual Processes
These require human judgment and are not suitable for full automation:
| Tool Type | Examples | Why Human Needed |
|---|---|---|
| Code Review | GitHub PR Review | Requires understanding business context and architectural intent |
| Architecture Decisions | ADR documents | Requires global perspective and long-term thinking |
| Dependency Upgrades | Major version upgrades | Requires evaluating impact of breaking changes |
Feedback Loop Design
Good engineering architecture creates a fast feedback loop:
Developer intent โ AI generates code โ Tools detect instantly โ Feedback to AI โ AI fixes โ Validation passesWhy Feedback Loops Matter?
| Feature | Traditional Tool Feedback | AI Self-Assessment |
|---|---|---|
| Determinism | โ Clear rules, consistent results | โ May hallucinate |
| Coverage | โ 100% checks all code | โ May miss edge cases |
| Speed | โ Millisecond response | โ ๏ธ Requires extra inference time |
| Reliability | โ Tools donโt lie | โ AI may be overconfident |
Chapter Contents
| Section | Content | Core Goal |
|---|---|---|
| Directory Structure | AI-friendly directory organization, small file strategy | Optimize AI context reading |
| Database Schema | Unified ERD management, schema file strategy | Help AI understand data models |
| Architecture Design | Modularity, strong typing, interface contracts | Establish clear code organization |
| Static Analysis Tools | ESLint, Ruff, SpotBugs | Provide deterministic feedback |
| Automated Testing | Vitest, PyTest, Playwright | Verify functional correctness |
| CI/CD Pipeline | GitHub Actions, pipelines | Build automated feedback loops |
Next Steps
Ready? Letโs start with Project Structure Optimization to learn how to design an AI-friendly project organization.