AI 时代“提示词友好型”工程目录：从数据表到伪代码的极致组织法 ——让任何大模型 3 秒读懂需求、10 分钟生成可上线代码

本文提出了一套面向AI编程的工程目录组织方法，通过5个核心目录（schema/、pseudocode/、tech/、edge/、test/）和3个配置文件，将传统"人类可读"的工程结构升级为"模型先读、人类后读"的范式。该方案将需求拆解为高频模式，以目录级提示词优化AI代码生成质量，经42个项目验证可将一次通过率从30%提升至83%。每个目录详细规定了文件命

黑金IT

487人浏览 · 2025-09-12 20:36:25

黑金IT · 2025-09-12 20:36:25 发布

AI 时代“提示词友好型”工程目录：从数据表到伪代码的极致组织法
——让任何大模型 3 秒读懂需求、10 分钟生成可上线代码

开场：为什么 90% 的“AI 编程”都在返工？

过去半年，我们用 GitHub Copilot、ChatGPT、Claude、CodeLlama 等 7 款主流模型接了 42 个外包项目，发现一个残酷事实：
“提示词写得再花哨，如果目录结构混乱，AI 生成的代码 80% 要重写。”
痛点集中爆发在三处：

表结构散落在 17 个微信群聊天记录里，模型根本不知道主键叫 id 还是 user_id；
伪代码写在 PPT 里，字体还是图片，AI 直接 OCR 出一堆“□”；
程序员把 README 写成日记：“今天和产品吵了一架，登录先这样吧……”
于是，我们花了 2 个月时间，把“人类可读”升级为“模型先读、人类后读”，沉淀出这份 9 000 余字的最佳实践。
不夸张地说，只要目录按本文组织，AI 生成一次通过率能从 30% 提升到 83%（内部数据，42 项目均值）。

大模型本质上是“概率野兽”，它最擅长的是“模式匹配”。
因此，我们要把“需求”拆成“高频模式”，并放到目录级别，让模型一眼定位：

模式 1：表结构 → schema/
模式 2：业务规则 → pseudocode/
模式 3：技术栈约束 → tech/
模式 4：边界 case → edge/
模式 5：验收标准 → test/
目录即提示词，文件即上下文。
下文将逐层拆解，每个目录给出：
① 命名规范（正则级）
② 文件模板（复制即用）
③ AI 提示词片段（直接投喂）
④ 踩坑案例（带血带泪）

一级目录总览：5 文件夹 + 3 配置文件

project-root/
├── schema/ # 数据表结构
├── pseudocode/ # 业务伪代码
├── tech/ # 技术栈约束
├── edge/ # 边界与异常
├── test/ # 验收用例
├── .aiignore # 让 AI 跳过无用文件
├── .aiconfig.yml # 全局提示词变量
└── README.md # 人类入口

schema/：让模型一眼看懂“数据世界”

3.1 目录粒度

一表一文件，文件名 = 表名.snake_case.sql
超过 30 个字段的宽表，拆成“主表 + 子表”两个文件
枚举表统一放到 schema/enums/ 目录，避免污染根目录

3.2 文件头模板（必须写，AI 靠它识别业务域）

-- =====================================================  
-- Table: user_payment_methods  
-- Domain: Payment  
-- Business Owner: 财务组 <finance@company.com>  
-- AI Hint: 敏感字段，生成代码需脱敏  
-- =====================================================

3.3 字段注释“三必须”

业务含义（中文）
取值单位（秒/分/元/百分比）
是否敏感（GDPR/PCI/国密）

示例：

`annual_income` DECIMAL(12,2) COMMENT '用户年收入，单位元，敏感字段，需脱敏展示',

3.4 目录级 README（供模型快速索引）

# schema/ 目录说明  
- enums/     枚举表，AI 生成代码时请用常量引用，禁止硬编码魔法值  
- main/      核心业务表  
- log/       日志类表，允许模型选择分库分表策略

3.5 AI 提示词片段（可直接贴到聊天框）

以下表结构均在 schema/ 目录，请使用 COMMENT 中的中文含义作为字段别名，  
敏感字段必须脱敏，金额统一转成分存储，时间统一用 DATETIME(3)。

pseudocode/：把“人话”转成“模型语法”

4.1 文件粒度

一功能一文件，文件名 = use_case.snake_case.md
功能过大时，用“子目录 + 数字前缀”方式展开：
pseudocode/order/01_create.md
pseudocode/order/02_cancel.md

4.2 伪代码语法（兼容自然语言 + 伪 DSL）

@actor 用户  
@trigger 点击“立即下单”  
@guard 库存 > 0 且 用户未被封禁  
@step 1 扣减库存（悲观锁）  
@step 2 创建订单快照（order_snapshot）  
@step 3 发送延迟消息，15 分钟关闭订单  
@exception 库存不足抛 STOCK_INSUFFICIENT_ERROR  
@biz 日志需记录 user_id, sku_id, 快照 MD5

4.3 目录级 README（让模型知道优先级）

# pseudocode/ 目录说明  
- P0 目录为阻塞主流程，AI 必须 100% 覆盖异常分支  
- P1 目录允许用 TODO 占位，后续迭代

4.4 AI 提示词片段

以下伪代码采用 @step @exception @biz 标签，  
请生成 Python 3.11 代码，使用 SQLAlchemy 2.0 语法，  
事务粒度为 @step1-3 整体提交，异常回滚。

tech/：技术栈约束，让模型“不乱来”

5.1 文件列表

stack.yml # 技术栈版本锁定
constraint.md # 公司级编码规约
package.json.lock # 前端依赖精确版本
requirements.txt # Python 依赖精确版本

5.2 stack.yml 示例

python: 3.11.4  
framework:  
  name: FastAPI  
  version: 0.112.0  
orm:  
  name: SQLAlchemy  
  version: 2.0.30  
database:  
  driver: mysql-connector-python  
  version: 8.3.0  
禁止:  
  - 不允许使用 Raw SQL 拼接  
  - 不允许在 for 循环里查 DB（N+1）

5.3 AI 提示词片段

技术约束以 tech/stack.yml 为准，  
禁止出现低版本方言，必须兼容 MySQL 8.0.35 的 ONLY_FULL_GROUP_BY。

6.1 文件命名

正例：duplicate_email_registration.md
反例：error.md（太宽泛，模型看不懂）

6.2 内容模板

# 场景：邮箱重复注册  
## 触发条件  
用户 A 用 X 邮箱注册，用户 B 用 X 邮箱再次注册。  
## 期望行为  
返回 422，错误码 40001，提示“邮箱已注册，请直接登录或找回密码”  
## 易错点  
AI 容易生成 200 OK + 覆盖旧账号，导致数据丢失

6.3 AI 提示词片段

若出现 edge/ 目录同名场景，必须优先覆盖 edge/ 中的期望行为，  
禁止擅自修改状态码及错误码。

test/：验收用例 = 反向提示词

7.1 文件命名

单元测试：test__.py
端到端：e2e_<use_case>.http

7.2 .http 文件示例（VS Code REST Client 插件直接跑）

### 登录成功  
POST http://localhost:8000/api/v1/login  
Content-Type: application/json  

{  
  "username": "alice",  
  "password": "A123456x"  
}  

> {%  
client.test("断言返回 200 且带 token", function() {  
  client.assert(response.status === 200, "状态码不是 200");  
  client.assert(response.body.token.length > 10, "token 异常");  
})  
%}

7.3 AI 提示词片段

生成代码后，必须同步生成 test/ 下的对应用例，  
并保证 e2e 文件在本地 docker-compose 环境一次跑通。

隐藏神器：.aiignore 与 .aiconfig.yml

8.1 .aiignore
作用：让模型跳过无关文件，节省上下文长度
示例：

*.log  
node_modules/  
.vscode/  
*.drawio

8.2 .aiconfig.yml
作用：全局变量模板，一处修改，全项目生效
示例：

variables:  
  COMPANY_NAME: 星际旅行公司  
  COPYRIGHT: "Copyright © 2025 星际旅行公司，GPL-3.0"  
  DEFAULT_LOCALE: zh-CN  
prompts:  
  head: |  
    你是 ${COMPANY_NAME} 的资深工程师，代码必须带 GPLv3 协议头，  
    默认语言 ${DEFAULT_LOCALE}，时区 Asia/Shanghai。

完整目录树（含隐藏文件，可直接 tree -a）

project-root/
├── .aiignore
├── .aiconfig.yml
├── schema/
│ ├── README.md
│ ├── enums/
│ │ ├── order_status.sql
│ │ └── user_level.sql
│ ├── main/
│ │ ├── user.sql
│ │ ├── order.sql
│ │ └── sku.sql
│ └── log/
│ └── user_login_log.sql
├── pseudocode/
│ ├── README.md
│ ├── P0/
│ │ ├── login.md
│ │ ├── register.md
│ │ └── checkout.md
│ └── P1/
│ └── coupon.md
├── tech/
│ ├── stack.yml
│ ├── constraint.md
│ ├── requirements.txt
│ └── package.json.lock
├── edge/
│ ├── duplicate_email_registration.md
│ └── sku_negative_stock.md
├── test/
│ ├── test_user_login.py
│ └── e2e_login.http
└── README.md

实战：一条提示词，让 AI 10 分钟生成生产级代码

把下面整段贴给任意大模型（已验证 GPT-4、Claude-3、CodeLlama-70B 有效）：

上下文：  
- 技术栈见 tech/stack.yml  
- 表结构见 schema/main/user.sql 与 schema/main/order.sql  
- 业务规则见 pseudocode/P0/checkout.md  
- 边界场景见 edge/sku_negative_stock.md  
- 验收标准见 test/e2e_checkout.http  

任务：  
用 Python 3.11 + FastAPI + SQLAlchemy 2.0 生成完整可运行代码，  
包含：  
1. Pydantic 模型  
2. CRUD 层  
3. 路由层  
4. 单元测试（pytest）  
5. e2e 用例（.http 文件）  

要求：  
- 代码必须兼容 MySQL 8.0.35 的 ONLY_FULL_GROUP_BY  
- 所有敏感字段脱敏  
- 默认时区 Asia/Shanghai  
- 文件头带GPLv3协议  
- 注释用中英双语  
- 生成后给出本地 docker-compose 一键启动命令

踩坑汇总：42 项目血泪史

11.1 模型把 created_at 当成字符串
解法：schema 字段 COMMENT 写明“DATETIME(3)”并给 AI 提示“时间类型禁止用字符串”。

11.2 模型生成 UUID 主键，线上表是 BIGINT
解法：tech/constraint.md 写明“所有新表主键必须为 BIGINT 自增，禁止 UUID”。

11.3 模型把日元当人民币，金额 *100 逻辑错误
解法：schema 字段 COMMENT 写“单位分，货币类型见 currency_code 枚举”。

11.4 模型忽略 edge/ 目录，覆盖旧账号
解法：在伪代码里用 @include edge/duplicate_email_registration.md 显式引用。

扩展：多语言、多端、多云场景

12.1 多语言
新增 locale/ 目录，按 IETF 语言标签拆分：
locale/zh-CN/login.json
locale/en-US/login.json
AI 提示词：
“所有返回给前端的错误文案，必须从 locale/${DEFAULT_LOCALE} 读取，禁止硬编码。”

12.2 多端（小程序 + App + Web）
在 pseudocode/ 目录下再分端：
pseudocode/mp/ # 小程序专属流程
pseudocode/app/ # App 专属流程
AI 提示词：
“生成小程序代码时，优先参考 pseudocode/mp/，禁止出现 Web 专属 DOM API。”

12.3 多云（阿里云 + AWS 双活）
在 tech/ 目录新增 cloud/
cloud/alicloud.yml
cloud/aws.yml
AI 提示词：
“生成 Terraform 脚本时，必须同时输出 alicloud 与 aws 两套资源，Region 变量从 cloud/ 读取。”

我们坚信：
“提示词工程”的尽头是“目录工程”。
当目录本身成为结构化提示词，AI 编程就从“咒语时代”进入“工程时代”。
把本文的目录树复制到你的新仓库，
下一次，你只需敲三个字：
“按目录。”

2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

前后端分离适老化背景下老年人康养知识线上学习平台系统|SpringBoot+微信小程序+MyBatis+MySQL完整源码+部署教程

2048 AI社区

一文带你熟悉大模型提示词技巧Prompt Engineering

2048 AI社区

4. 信息安全技术基础知识

敌对势力的破坏、恶意软件的入侵、黑客攻击、利用计算机犯罪、网络有害信息泛滥、个人隐私泄露等等，对信息安全构成了极大威胁，严重危害人民的身心健康，危害社会的安定团结，危害了国家的主权与发展。信息的存储安全包括信息使用的安全(如用户的标识与验证、用户存取权限限制、安全问题跟踪等)、系统安全监控、计算机病毒防治、数据的加密和防止非法的攻击等。Client（攻击者） → Handler（主控端） → Ag

2048 AI社区

所有评论(0)

查看更多评论

黑金IT

@ylong52

已为社区贡献10条内容