# 🧠 AI-First Project Engineering Guide

---

## 1️⃣ Think in SYSTEMS, not code

Before writing *any* code, always answer these 4 questions:

1. **What problem am I solving?**
    
2. **What inputs go in?**
    
3. **What outputs come out?**
    
4. **What can fail?**
    

👉 If you can’t explain this in 5 lines, don’t code yet.

**Mental model**

```plaintext
Input → Validation → Processing → Output
           ↑
        Failure paths
```

---

## 2️⃣ Choose tech based on change, not hype

### Golden rule

> Pick the tech that makes **change cheap**, not development fast.

### Safe default stack

* **Backend:** Python + FastAPI
    
* **AI/LLM:** Python
    
* **Frontend:** Next.js (only if needed)
    
* **DB:** Start simple → scale later
    

### Ask yourself:

* Will logic change often? → Python
    
* Will AI be core? → Python
    
* Need extreme speed? → Go (later)
    

---

## 3️⃣ Folder structure is your first quality signal

Bad structure = future pain.

### Always separate:

| Layer | Purpose |
| --- | --- |
| `routes / api` | HTTP only |
| `services` | Business logic |
| `models / schemas` | Data contracts |
| `utils` | Shared helpers |
| `core` | Config, logging |
| `tests` | Safety net |

> **If a file grows beyond ~300 lines → split it**

---

## 4️⃣ AI code ≠ human code (you must control it)

### Never let AI:

❌ Decide architecture  
❌ Mix logic + API  
❌ Name things randomly  
❌ Skip types & docs

### You decide:

* File structure
    
* Naming
    
* Boundaries
    

AI is a **junior dev with speed**, not a lead engineer.

---

## 5️⃣ Always design contracts first (very important)

Before logic:

* Define **request schema**
    
* Define **response schema**
    

Example mindset:

```json
INPUT  →  { data, options }
OUTPUT →  { status, result, meta }
```

Why this matters:

* APIs stay stable
    
* AI changes won’t break consumers
    
* Easy debugging
    

---

## 6️⃣ Single Responsibility Principle (non-negotiable)

One function = one job.

❌

```python
analyze_and_call_llm_and_save()
```

✅

```python
fetch_data()
analyze_data()
call_llm()
store_result()
```

This is what keeps AI projects maintainable.

---

## 7️⃣ Treat LLMs as UNRELIABLE external APIs

LLMs can:

* Timeout
    
* Hallucinate
    
* Return invalid JSON
    
* Change behavior
    

### Always:

* Validate output
    
* Retry safely
    
* Fallback gracefully
    

Example mindset:

```plaintext
Call LLM
→ Validate schema
→ If fail → retry / default
→ Log everything
```

---

## 8️⃣ Logging > debugging

If you don’t log, you’ll suffer later.

### Minimum logs:

* Request received
    
* AI call started
    
* AI call failed
    
* AI call success
    

Log **intent**, not noise.

---

## 9️⃣ Configuration & secrets discipline

**Rules**

* `.env` only
    
* Never hardcode keys
    
* One config file
    

If you break this once, it *will* bite you.

---

## 🔟 Error handling is product quality

Don’t expose raw errors.

Always return:

```json
{
  "status": "error",
  "message": "Human readable",
  "code": "LLM_TIMEOUT"
}
```

Users don’t care about stack traces.

---

## 1️⃣1️⃣ Minimal testing mindset (enough is enough)

You don’t need 100% coverage.

You NEED:

* One health test
    
* One happy path
    
* One failure path
    

That’s it.

---

## 1️⃣2️⃣ Version everything that touches AI

AI logic **will change**.

Always version:

* APIs (`/v1`, `/v2`)
    
* Prompts
    
* Schemas
    

Example:

```plaintext
prompt_v1.txt
prompt_v2.txt
```

---

## 1️⃣3️⃣ Prompting rules for AI tools (Cursor, Copilot)

### Always include:

1. Role
    
2. Tech stack
    
3. Rules
    
4. Task
    

### Template (save this)

```plaintext
You are a senior engineer.

Stack:
- Python
- FastAPI

Rules:
- Clean architecture
- Type hints
- No logic in routes

Task:
<your task>
```

---

## 1️⃣4️⃣ Use AI for THESE things only

Best use cases:

* Boilerplate
    
* Refactoring
    
* Edge case discovery
    
* Docs
    
* Test generation
    

Worst use cases:

* Architecture decisions
    
* Security logic
    
* Data modeling
    

---

## 1️⃣5️⃣ Code review mindset (even solo)

Before committing, ask:

* Can I delete this?
    
* Can I simplify this?
    
* Can someone else read this?
    

If answer is “no” → refactor.

---

## 1️⃣6️⃣ Keep complexity proportional to value

Don’t add:

* Microservices
    
* Queues
    
* Caching  
    until pain forces you.
    

Simple &gt; clever.

---

## 1️⃣7️⃣ Documentation is not optional

Every project should have:

* README
    
* Setup steps
    
* API summary
    
* Known limitations
    

Future you will thank you.

---

## 1️⃣8️⃣ The final mental checklist (use daily)

Before pushing code:

* ✅ Clear structure
    
* ✅ Types present
    
* ✅ Logs added
    
* ✅ Errors handled
    
* ✅ AI output validated
    

If **3+ are missing**, stop and fix.

---

## 🧩 One sentence to remember everything

> **“I design the system, AI helps me implement it.”**

---