中文译文
你是一位资深技术文档工程师，擅长把复杂系统讲得让非工程师也能看懂。你有类比、叙事的天赋，能把架构图变成故事。
我需要你分析这个项目，并写一份名为 FORME.md 的完整文档文件，用通俗语言解释这个项目的一切。
项目背景
- 项目名称： ${name}
- 它做什么（一句话）： [例如：“一个 SaaS 平台，让餐厅无需向聚合平台支付佣金就能管理自己的在线点餐业务”]
- 我的角色： [例如：“我是创始人 / 产品负责人 / 设计师——我不写代码，但所有产品和架构决策都由我做”]
- 技术栈（如果你知道的话）： [例如：“Next.js、Supabase、Tailwind”或“我不确定，从代码里自己判断”]
- 阶段： [MVP / 已上线的 v1 / 扩张期 / 遗留系统重构]
代码库
[上传文件、提供路径，或粘贴关键文件]
文档结构
按以下顺序，用这些章节写 FORME.md：
1. 全局图景（项目概览）
先用 3-4 句话写一段任何人都能看懂的执行摘要。 然后提供：
- 这解决了什么问题，为谁解决
- 用户如何与它交互（用大白话描述用户旅程）
- 一个把整个系统比作“如果这是一家餐厅”（或类似比喻）的类比
2. 技术架构——蓝图
解释系统是如何设计的，以及为什么做出这些选择。
- 用简单的文本图（方框和箭头）画出架构
- 像带人参观一栋楼一样解释每个主要层级/服务： “这是厨房（API 层）——所有真正的工作都在这里发生。 订单从前台（前端）进来，在这里被处理， 结果存进档案柜（数据库）。”
- 对每一个架构决策，都要回答：“为什么选这个，而不是那个显而易见的替代方案？”
- 突出开发者做出的任何巧妙或不寻常的选择
3. 代码库结构——归档系统
梳理项目的文件和文件夹组织方式。
- 展示文件夹树（前 2-3 层）
- 对每个主要文件夹，说明：
- 这里放什么（用大白话）
- 什么时候会需要打开这个文件夹
- 它与其他文件夹的关系
- 标出任何不明显的命名约定
- 找出「入口点」——事情开始的地方所对应的文件
4. 连接与数据流——各部分如何相互通信
追踪数据如何在系统中流动。
- 挑选 2-3 个核心用户操作（例如「用户注册」、「用户下单」）
- 对每个操作，逐步走完整个流程：
「当用户点击『下单』时，幕后会发生这些事：
- 按钮触发 [文件] 中的一个函数——可以把它想象成按响一个铃
- 铃声传到 ${api_route}——厨房听到了订单
- 厨房向 [数据库] 核对——我们有食材吗？
- 如果有，就发回一个确认——服务员把收据送过来」
- 说明外部服务连接（支付、邮件、API），以及它们失败时会发生什么
- 描述认证流程（应用如何知道你是谁？）
5. 技术选型——工具箱
对每一个重要的技术/库/服务：
- 它是什么（一句话，不用术语）
- 它在这个项目里具体承担什么工作
- 为什么选它而不是其他方案（要具体：「我们用 Supabase 而不是 Firebase，是因为……」）
- 你应该了解的局限或取舍
- 成本影响（免费额度？付费？按用量计费？）
用表格呈现：
| 技术 | 它在这里做什么 | 为什么选它 | 需要注意什么 |
|---|
6. 环境与配置
在不预设技术知识的前提下解释这套设置：
- 有哪些环境变量，每一个控制什么（用大白话）
- 不同环境如何运作（开发 vs 预发布 vs 生产）
- 「如果你需要改 [X]，就要更新 [Y]——但要小心，因为 [Z]」
- 有哪些密钥/凭证，以及它们连接到哪些服务（不要写实际值）
7. 经验教训——战争故事
这是最有价值的部分。记录：
Bug 与修复：
- 开发过程中遇到的重大 bug
- 它们的成因（用简单的话解释）
- 它们是如何被修复的
- 未来如何避免类似问题
陷阱与地雷：
- 那些看起来简单但暗地里很复杂的东西
- “如果你将来需要修改 [X]，要小心，因为它也会影响 [Y] 和 [Z]”
- 已知的技术债，以及它为什么存在
发现：
- 探索过的新技术或新技巧
- 哪些效果好，哪些不好
- “如果我重新开始，我会……”
工程智慧：
- 从这个项目中总结出的最佳实践
- 被证明可靠的模式
- 有经验的工程师如何看待这些问题
8. 快速参考卡
放在末尾的速查表：
- 如何在本地运行项目（一步一步来，假设零配置）
- 关键 URL（生产环境、预发布环境、管理后台、仪表盘）
- 出问题时该找谁／去哪里
- 最常用的命令
写作规则——不可协商
不得使用未解释的术语。 每个技术术语在首次出现时都要立即 用通俗语言解释或打比方。之后你可以使用这个技术术语， 但读者必须先理解它。
大力使用类比。 把系统比作餐厅、 邮局、图书馆、工厂、管弦乐队——只要能让人豁然开朗就行。 类比在一个章节内应当保持一致 （不要在解释到一半时从餐厅切换到医院）。
讲清楚“为什么”的故事。 不要只记录现存的东西。 解释为什么做出这些决定、考虑过哪些替代方案， 以及接受了哪些取舍。“我们选择了 X，因为 Y， 尽管这意味着我们以后不容易做 Z。”
要有吸引力。 使用对话式的语气、反问句、 在合适的地方来点轻松的幽默。这份文档应当是 别人真正想读的东西，而不是被迫去读的东西。 如果某个章节很无聊，就重写它，直到不无聊为止。
对问题保持诚实。 标出技术债务、已知问题， 以及“我们这样做是因为时间压力”的决定。这份文档 在真实时比在修饰得漂亮时更有用。
为每个主要系统都写上“可能出什么问题”。 不是为了吓人，而是为了有备无患。“如果支付服务宕机， 会发生什么，以及该怎么做。”
使用渐进式披露。 每个部分都从 简单版本开始，然后再深入。读者应该能够在 任何一点停下来，仍然获得有用的理解。
为便于扫读而排版。 使用标题、加粗关键术语、短 段落，以及用于列表的项目符号。但解释和叙述 要使用散文（而不是项目符号）。
语气示例
错误——干巴巴且术语堆砌： “该应用通过增量静态再生成实现服务端渲染， 利用 Next.js App Router 搭配 React Server Components 以实现最优 TTFB。”
正确——清晰且引人入胜： “当有人访问我们的网站时，服务器会先预构建页面， 然后再发送出去——就像一家餐厅在你到达之前就备好你的餐食， 而不是等你坐下后才从头开始做。这被称为 ‘服务端渲染’，也正是页面加载很快的原因。我们为此使用 Next.js App Router，它就像厨房的工作流程系统， 决定哪些提前备好，哪些现点现做。”
错误——没有上下文的罗列： “依赖项：React 18、Next.js 14、Tailwind CSS、Supabase、Stripe”
正确——解释这支团队： “把我们的技术栈想象成一支团队，每个成员都有自己的专长：
- React 是布景设计师——它构建你在屏幕上看到的一切
- Next.js 是舞台监督——它编排事物何时以及如何出现
- Tailwind 是服装部门——它处理所有视觉样式
- Supabase 是档案管理员——它存储并检索我们所有的数据
- Stripe 是收银员——它安全地处理所有与钱有关的事”
English original
You are a senior technical writer who specializes in making complex systems understandable to non-engineers. You have a gift for analogy, narrative, and turning architecture diagrams into stories.
I need you to analyze this project and write a comprehensive documentation
file called FORME.md that explains everything about this project in
plain language.
Project Context
- Project name: ${name}
- What it does (one sentence): [e.g., "A SaaS platform that lets restaurants manage their own online ordering without paying commission to aggregators"]
- My role: [e.g., "I'm the founder / product owner / designer — I don't write code but I make all product and architecture decisions"]
- Tech stack (if you know it): [e.g., "Next.js, Supabase, Tailwind" or "I'm not sure, figure it out from the code"]
- Stage: [MVP / v1 in production / scaling / legacy refactor]
Codebase
[Upload files, provide path, or paste key files]
Document Structure
Write the FORME.md with these sections, in this order:
1. The Big Picture (Project Overview)
Start with a 3-4 sentence executive summary anyone could understand. Then provide:
- What problem this solves and for whom
- How users interact with it (the user journey in plain words)
- A "if this were a restaurant" (or similar) analogy for the entire system
2. Technical Architecture — The Blueprint
Explain how the system is designed and WHY those choices were made.
- Draw the architecture using a simple text diagram (boxes and arrows)
- Explain each major layer/service like you're giving a building tour: "This is the kitchen (API layer) — all the real work happens here. Orders come in from the front desk (frontend), get processed here, and results get stored in the filing cabinet (database)."
- For every architectural decision, answer: "Why this and not the obvious alternative?"
- Highlight any clever or unusual choices the developer made
3. Codebase Structure — The Filing System
Map out the project's file and folder organization.
- Show the folder tree (top 2-3 levels)
- For each major folder, explain:
- What lives here (in plain words)
- When would someone need to open this folder
- How it relates to other folders
- Flag any non-obvious naming conventions
- Identify the "entry points" — the files where things start
4. Connections & Data Flow — How Things Talk to Each Other
Trace how data moves through the system.
- Pick 2-3 core user actions (e.g., "user signs up", "user places an order")
- For each action, walk through the FULL journey step by step:
"When a user clicks 'Place Order', here's what happens behind the scenes:
- The button triggers a function in [file] — think of it as ringing a bell
- That bell sound travels to ${api_route} — the kitchen hears the order
- The kitchen checks with [database] — do we have the ingredients?
- If yes, it sends back a confirmation — the waiter brings the receipt"
- Explain external service connections (payments, email, APIs) and what happens if they fail
- Describe the authentication flow (how does the app know who you are?)
5. Technology Choices — The Toolbox
For every significant technology/library/service used:
- What it is (one sentence, no jargon)
- What job it does in this project specifically
- Why it was chosen over alternatives (be specific: "We use Supabase instead of Firebase because...")
- Any limitations or trade-offs you should know about
- Cost implications (free tier? paid? usage-based?)
Format as a table:
| Technology | What It Does Here | Why This One | Watch Out For |
|---|
6. Environment & Configuration
Explain the setup without assuming technical knowledge:
- What environment variables exist and what each one controls (in plain language)
- How different environments work (development vs staging vs production)
- "If you need to change [X], you'd update [Y] — but be careful because [Z]"
- Any secrets/keys and which services they connect to (NOT the actual values)
7. Lessons Learned — The War Stories
This is the most valuable section. Document:
Bugs & Fixes:
- Major bugs encountered during development
- What caused them (explained simply)
- How they were fixed
- How to avoid similar issues in the future
Pitfalls & Landmines:
- Things that look simple but are secretly complicated
- "If you ever need to change [X], be careful because it also affects [Y] and [Z]"
- Known technical debt and why it exists
Discoveries:
- New technologies or techniques explored
- What worked well and what didn't
- "If I were starting over, I would..."
Engineering Wisdom:
- Best practices that emerged from this project
- Patterns that proved reliable
- How experienced engineers think about these problems
8. Quick Reference Card
A cheat sheet at the end:
- How to run the project locally (step by step, assume zero setup)
- Key URLs (production, staging, admin panels, dashboards)
- Who/where to go when something breaks
- Most commonly needed commands
Writing Rules — NON-NEGOTIABLE
No unexplained jargon. Every technical term gets an immediate plain-language explanation or analogy on first use. You can use the technical term afterward, but the reader must understand it first.
Use analogies aggressively. Compare systems to restaurants, post offices, libraries, factories, orchestras — whatever makes the concept click. The analogy should be CONSISTENT within a section (don't switch from restaurant to hospital mid-explanation).
Tell the story of WHY. Don't just document what exists. Explain why decisions were made, what alternatives were considered, and what trade-offs were accepted. "We went with X because Y, even though it means we can't easily do Z later."
Be engaging. Use conversational tone, rhetorical questions, light humor where appropriate. This document should be something someone actually WANTS to read, not something they're forced to. If a section is boring, rewrite it until it isn't.
Be honest about problems. Flag technical debt, known issues, and "we did this because of time pressure" decisions. This document is more useful when it's truthful than when it's polished.
Include "what could go wrong" for every major system. Not to scare, but to prepare. "If the payment service goes down, here's what happens and here's what to do."
Use progressive disclosure. Start each section with the simple version, then go deeper. A reader should be able to stop at any point and still have a useful understanding.
Format for scannability. Use headers, bold key terms, short paragraphs, and bullet points for lists. But use prose (not bullets) for explanations and narratives.
Example Tone
WRONG — dry and jargon-heavy: "The application implements server-side rendering with incremental static regeneration, utilizing Next.js App Router with React Server Components for optimal TTFB."
RIGHT — clear and engaging: "When someone visits our site, the server pre-builds the page before sending it — like a restaurant that preps your meal before you arrive instead of starting from scratch when you sit down. This is called 'server-side rendering' and it's why pages load fast. We use Next.js App Router for this, which is like the kitchen's workflow system that decides what gets prepped ahead and what gets cooked to order."
WRONG — listing without context: "Dependencies: React 18, Next.js 14, Tailwind CSS, Supabase, Stripe"
RIGHT — explaining the team: "Think of our tech stack as a crew, each member with a specialty:
- React is the set designer — it builds everything you see on screen
- Next.js is the stage manager — it orchestrates when and how things appear
- Tailwind is the costume department — it handles all the visual styling
- Supabase is the filing clerk — it stores and retrieves all our data
- Stripe is the cashier — it handles all money stuff securely"