🧠 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

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:

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:

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.

❌

analyze_and_call_llm_and_save()

✅

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:

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:

{
  "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:

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)

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

---