这是一个非常关键的问题。

很多 AI 工程项目最大的问题是：

只有代码
没有设计
没有演进过程
没有工程文档

结果就是：

• 看起来像 demo
• 不像真正系统
• 无法体现架构能力
• 面试时说不清设计决策

而真正专业的 AI 工程 portfolio，通常是：

MVP → Architecture Evolution → Productionization

你要展示的是：

“我不仅会做 demo，我知道系统怎么成长。”

这才是高级 AI 工程师的感觉。

---

你应该怎么理解整个过程

整个项目应该分成：

1. Idea
2. MVP
3. Engineering
4. Productionization
5. Scalability

每个阶段的文档完全不同。

---

第一阶段：MVP 阶段

这是：

“验证系统是否成立”

目标不是稳定性。

目标是：

证明：
- workflow成立
- agent协作成立
- tool调用成立
- state流转成立

---

MVP 阶段必须完成的文档（重点）

这里只需要 5 个。

很多人会疯狂写文档。

没必要。

---

1. README（最重要）

这是项目门面。

必须包含：

项目简介

例如：

# Multi-Agent Research Assistant

A multi-agent research workflow system built with LangGraph.

Features:
- task planning
- web research
- summarization
- markdown report generation

---

Architecture Diagram

用 Mermaid。

---

Tech Stack

例如：

- LangGraph
- FastAPI
- OpenAI
- Tavily
- Docker

---

Quick Start

这是必须的。

别人能不能跑起来非常重要。

---

2. PRD（非常短）

文件：

docs/prd.md

内容：

用户问题

例如：

单LLM无法稳定完成复杂research任务

---

MVP目标

通过多个agent拆分任务
提升research质量

---

非目标（非常重要）

比如：

不做：
- 长期记忆
- autonomous loop
- browser automation

这会显得你很专业。

因为：

真正工程师知道什么“不做”。

---

3. Architecture Doc（核心）

文件：

docs/architecture.md

这是最关键文档之一。

你要写：

---

Agent Responsibilities

例如：

Agent	Responsibility
Planner	拆分research任务
Researcher	调用搜索工具
Summarizer	生成最终报告

---

Workflow

例如：

User Query
→ Planner
→ Research Tasks
→ Search
→ Summarize
→ Final Report

---

State Definition

这是 AI 工程感的核心。

class AgentState(TypedDict):
    query: str
    tasks: list[str]
    search_results: list[str]
    final_report: str

---

4. Decision Log（高级感来源）

这个很重要。

文件：

docs/decisions.md

记录：

为什么用 LangGraph？

为什么不用 AutoGen？

为什么使用 centralized orchestration？

为什么不用 autonomous agents？

这会让你看起来像：

真正做过架构权衡的人。

而不是 tutorial copier。

---

5. TODO / Roadmap

文件：

ROADMAP.md

例如：

## v1 MVP
- planner
- research
- summarize

## v2
- memory
- retry
- tracing

## v3
- async execution
- evaluation pipeline
- human review

这个特别重要。

因为它能体现：

你知道系统如何演进。

---

MVP 阶段不要做的事情

不要：

• Kubernetes
• 微服务
• Redis Cluster
• Kafka
• complicated memory
• 20 agents
• auth system

这些都是：

过早工程化

很多 AI 项目死在这里。

---

第二阶段：从 MVP 到 Production

这里开始真正体现 AI 工程能力。

---

生产化真正增加的东西

你会开始遇到：

- latency
- retry
- timeout
- hallucination
- observability
- token cost
- concurrency
- evaluation

这时：

项目才真正开始。

---

Production 阶段新增文档

这里开始需要：

---

1. System Design Doc

文件：

docs/system-design.md

这里开始写：

---

High-Level Architecture

例如：

---

Scalability

例如：

• async execution
• task queue
• parallel research

---

Reliability

例如：

• retries
• fallback models
• rate limiting

---

2. Evaluation Doc（非常关键）

AI 系统和普通系统最大区别：

需要 evaluation。

文件：

docs/evaluation.md

你需要定义：

---

Metrics

例如：

Metric	Meaning
relevance	搜索结果相关性
factuality	幻觉率
latency	响应时间
token_cost	token成本

---

Eval Dataset

例如：

[
  {
    "query": "...",
    "expected_topics": [...]
  }
]

---

3. Observability Doc

文件：

docs/observability.md

包括：

• tracing
• logs
• token usage
• agent transitions
• failures

---

4. API Spec

文件：

docs/api.md

例如：

POST /research

Request:

{
  "query": "Latest LLM orchestration frameworks"
}

---

5. Deployment Doc

文件：

docs/deployment.md

包括：

• Docker
• environment variables
• CI/CD
• cloud deployment

---

第三阶段：真正高级项目会出现的文档

如果你做到这里。

已经超过很多 AI 工程师。

你会开始写：

---

ADR（Architecture Decision Record）

例如：

ADR-001-use-langgraph.md
ADR-002-centralized-orchestrator.md
ADR-003-state-store-selection.md

这是高级工程团队常见东西。

---

Runbook

例如：

如何处理agent失败
如何恢复workflow
如何排查timeout

---

Incident Report

例如：

某次workflow循环爆token
如何修复

这个非常专业。

---

你现在最需要的其实是：

不是：

做复杂系统

而是：

展示“系统演进能力”

---

最后给你一个真正实用的建议

你现在应该：

第一步（今天）

创建：

/docs

然后写：

README.md
prd.md
architecture.md
decisions.md
ROADMAP.md

哪怕只有几十行。

---

第二步

再开始：

Claude Code implementation

这样：

你会发现：

你的代码会稳定很多。

因为：

架构已经提前收敛了。

---

最后一句很重要

真正高级的 portfolio：

不是：

“看我会写agent”

而是：

“看我如何把一个AI demo演化成真正系统”

这才是 AI 工程师最稀缺的能力。