makemd/archive/handover/00.md

我先给你一份比较完整的模板，然后再告诉你 **还有哪些文件能进一步优化 AI 编程体验**。

---

# PROJECT_MAP.md

# Project Map

This document provides a high-level map of the entire repository.

It is intended for both developers and AI systems to quickly understand the project structure.

---

# 1. Project Overview

Project Name: <PROJECT_NAME>

Purpose:

Describe the main goal of this project.

Example:

* Web backend service
* AI processing pipeline
* SaaS platform

Primary technologies:

* Language: <Python / Node / Go / etc>
* Framework: <FastAPI / Express / Spring / etc>
* Database: <PostgreSQL / MongoDB>

---

# 2. Repository Structure

Top-level structure:

```
project
 ├─ api
 ├─ service
 ├─ repository
 ├─ models
 ├─ utils
 ├─ config
 ├─ tests
 └─ scripts
```

---

# 3. Key Modules

## api

Handles external requests.

Responsibilities:

* routing
* validation
* response formatting

---

## service

Contains core business logic.

Responsibilities:

* orchestration
* domain rules
* transaction control

---

## repository

Handles data persistence.

Responsibilities:

* database queries
* ORM interactions
* caching layer

---

## models

Defines domain entities.

Examples:

* User
* Order
* Session

---

## utils

Shared helper functions.

Examples:

* date helpers
* logging
* validation utilities

---

# 4. Request Flow

Typical request lifecycle:

```
Client
  ↓
API Layer
  ↓
Service Layer
  ↓
Repository Layer
  ↓
Database
```

---

# 5. Important Entry Points

Main entry points:

```
main.py
app.ts
server.go
```

Startup flow:

1. load configuration
2. initialize services
3. register routes
4. start server

---

# 6. Configuration

Configuration files are located in:

```
config/
```

Types:

* environment variables
* database configuration
* feature flags

---

# 7. Testing Strategy

Tests are located in:

```
tests/
```

Structure mirrors source code.

Example:

```
service/user_service.py
tests/service/test_user_service.py
```

---

# 8. Coding Rules

See:

```
project_rules.md
```

---

# 9. Dependency Rules

See:

```
DEPENDENCY_MAP.md
```

---

# 10. AI Notes

Guidelines for AI tools:

* Keep files under 2000 lines
* Avoid circular dependencies
* Follow modular architecture
* Prefer small reusable functions

---

# 除了这些文件，还有哪些 AI 项目文件？

完整的 **AI-native 项目结构**通常会有这些：

```
AI_CONTEXT.md
PROJECT_MAP.md
MODULE_INDEX.md
DEPENDENCY_MAP.md
project_rules.md
```

但实际上还可以再加几个更高级的。

---

# 1️⃣ CODE_STYLE.md

专门给 AI 的代码风格。

例如：

```
indent: 4 spaces
naming: snake_case
class naming: PascalCase
error handling: explicit
```

AI生成代码会更一致。

---

# 2️⃣ API_MAP.md

如果项目有 API。

例如：

```
GET /users
POST /login
DELETE /session
```

AI可以直接知道接口结构。

---

# 3️⃣ DATA_SCHEMA.md

数据库结构说明。

例如：

```
User
- id
- email
- password_hash
```

AI生成 SQL / ORM 会更准。

---

# 4️⃣ WORKFLOW.md

业务流程。

例如：

```
user register
 ↓
email verification
 ↓
account activation
```

AI理解业务逻辑会更快。

---

# 最完整的 AI 项目结构（推荐）

```
project
 ├─ api
 ├─ service
 ├─ repository
 ├─ models
 ├─ utils
 ├─ tests

 ├─ project_rules.md
 ├─ PROJECT_MAP.md
 ├─ AI_CONTEXT.md
 ├─ MODULE_INDEX.md
 ├─ DEPENDENCY_MAP.md
 ├─ CODE_STYLE.md
 ├─ API_MAP.md
 └─ DATA_SCHEMA.md
```

---

# 一个很多人不知道的关键点

真正提升 AI 理解能力最大的文件其实不是这些，而是：

```
REPO_PROMPT.md
```

这是 **专门给 AI 的系统提示词**，告诉 AI：

* 如何修改代码
* 如何写模块
* 如何重构项目






下面是一套 **“AI 时代项目模板仓库结构（2026版）”**。
目标：**让 AI IDE、代码助手和人类开发者都能快速理解、导航和重构项目。**

---

# 一、完整仓库结构（推荐模板）

```text
project
├─ api/                # 外部接口层（HTTP / RPC / CLI）
│
├─ service/            # 核心业务逻辑
│
├─ repository/         # 数据访问层
│
├─ models/             # 数据模型 / schema
│
├─ components/         # 可复用组件（前端或服务模块）
│
├─ utils/              # 工具函数
│
├─ config/             # 配置文件
│
├─ scripts/            # 自动化脚本
│
├─ tests/              # 单元测试
│
├─ docs/               # 人类文档
│
├─ prompts/            # AI Prompt 模板
│
├─ embeddings/         # 向量索引配置
│
├─ project_rules.md
├─ AI_CONTEXT.md
├─ PROJECT_MAP.md
├─ MODULE_INDEX.md
├─ DEPENDENCY_MAP.md
├─ CODE_STYLE.md
├─ API_MAP.md
├─ DATA_SCHEMA.md
├─ WORKFLOW.md
├─ REPO_PROMPT.md
├─ README.md
└─ CHANGELOG.md
```

---

# 二、AI核心文件（最关键）

这些是 **AI理解项目的核心入口**。

### 1️⃣ AI_CONTEXT.md

作用：

* 项目总体介绍
* 技术栈
* 架构思想

AI第一时间读取。

---

### 2️⃣ PROJECT_MAP.md

作用：

* 仓库结构地图
* 入口文件
* 模块概览

让AI快速定位代码。

---

### 3️⃣ MODULE_INDEX.md

作用：

说明每个模块职责：

```text
api → 接口
service → 业务逻辑
repository → 数据访问
```

---

### 4️⃣ DEPENDENCY_MAP.md

定义 **依赖规则**：

```text
api → service
service → repository
repository → models
```

避免循环依赖。

---

### 5️⃣ project_rules.md

代码规范：

* 文件大小
* 模块拆分
* 命名规则

---

# 三、AI增强文件（提升 AI 代码能力）

### CODE_STYLE.md

代码风格：

```text
indent: 4 spaces
naming: snake_case
classes: PascalCase
comments: concise
```

AI生成代码更统一。

---

### REPO_PROMPT.md

**最重要的 AI 提示词文件**。

告诉 AI：

```text
如何修改代码
如何重构
如何写模块
```

例如：

```text
When modifying code:
- preserve architecture layers
- avoid circular dependencies
- keep files under 2000 lines
```

---

### prompts/

存放 AI prompt 模板：

```text
prompts/
  refactor.md
  bugfix.md
  feature.md
```

---

# 四、业务理解文件

这些帮助 AI **理解业务逻辑**。

### API_MAP.md

```text
GET /users
POST /login
DELETE /session
```

---

### DATA_SCHEMA.md

数据库结构：

```text
User
- id
- email
- password_hash
```

---

### WORKFLOW.md

业务流程：

```text
register
 ↓
email verification
 ↓
account activation
```

---

# 五、代码目录规范

推荐代码目录：

```text
api/
  user_controller
  auth_controller

service/
  user_service
  auth_service

repository/
  user_repository
```

调用链：

```text
API
 ↓
Service
 ↓
Repository
 ↓
Database
```

---

# 六、AI检索优化目录

为了让 AI IDE 更好检索代码：

```text
embeddings/
```

存储：

* 向量索引
* 代码摘要

一些 AI 工具会自动生成。

---

# 七、docs目录

给人类开发者：

```text
docs/
  architecture.md
  deployment.md
  dev_setup.md
```

---

# 八、文件大小建议

AI-friendly 项目规则：

```text
单文件 ≤ 2000 行
函数 ≤ 100 行
模块 ≤ 10 文件
```

---

# 九、典型调用链

```text
Client
 ↓
API
 ↓
Service
 ↓
Repository
 ↓
Database
```

AI最容易理解这种结构。

---

# 十、为什么这个结构重要

这种仓库结构可以：

* 降低 AI 上下文需求
* 提升代码生成质量
* 提升自动重构能力
* 提升项目可维护性

很多开发者用这种结构后：

```text
7B–13B 模型
```

就能处理 **大型项目重构**。

---

# 十一、最关键的三个文件

如果只选三个：

```text
AI_CONTEXT.md
PROJECT_MAP.md
REPO_PROMPT.md
```

这三个可以让 AI **30 秒理解项目**。

---
下面是一份 **增强版 `REPO_PROMPT.md`** 模板。它的定位是：为 AI 助手（如 Cursor、Windsurf、GitHub Copilot）提供**仓库级系统提示**，统一其改代码、加功能、重构时的行为准则。把它放在仓库根目录即可。

# REPO_PROMPT.md

## Purpose

This file defines how AI assistants should interact with this repository.
Follow these rules when reading, modifying, or generating code.

---

## 1. Architectural Principles

1. Respect the layered architecture:

   * api → service → repository → models
2. Never introduce circular dependencies.
3. Keep modules loosely coupled and cohesive.
4. Prefer composition over inheritance.

---

## 2. File and Function Limits

* Single file ≤ 2000 lines.
* Function ≤ 100 lines.
* Prefer splitting large logic into smaller modules.

If modifying a file that exceeds limits, propose a refactor.

---

## 3. Code Style

* Use descriptive variable and function names.
* Follow language conventions (snake_case or camelCase).
* Avoid abbreviations unless common (id, url, api).
* Add short comments only when logic is non-obvious.

Example:

Good:

```
createUserAccount
validateToken
fetchUserProfile
```

Bad:

```
handle
doTask
runLogic
```

---

## 4. Dependency Rules

Allowed:

```
api → service
service → repository
service → models
repository → models
utils → used by all
```

Forbidden:

```
repository → service
models → repository
api → repository
```

If a change would break these rules, refactor instead.

---

## 5. Refactoring Guidelines

When refactoring:

1. Preserve existing public interfaces.
2. Avoid unnecessary changes across unrelated modules.
3. Extract shared logic into utils if reused.
4. Ensure unit tests remain valid.

Prefer incremental refactoring over large rewrites.

---

## 6. Feature Development

When implementing a new feature:

1. Determine affected modules.
2. Add or modify models if needed.
3. Implement business logic in service layer.
4. Expose endpoints in api layer.

Never place business logic directly in api controllers.

---

## 7. Bug Fixing

When fixing bugs:

1. Identify root cause.
2. Modify the minimal number of files.
3. Avoid introducing new dependencies.
4. Add tests if possible.

---

## 8. Code Generation Behavior

When generating code:

* Follow existing project patterns.
* Reuse existing utilities and helpers.
* Avoid duplicating functionality.
* Maintain consistent naming conventions.

---

## 9. AI Context Strategy

To understand the project:

1. Read PROJECT_MAP.md.
2. Read MODULE_INDEX.md.
3. Check DEPENDENCY_MAP.md.
4. Then inspect relevant modules.

Do not assume knowledge of the entire repository.

---

## 10. Documentation Updates

If architectural changes occur:

Update the following files:

* PROJECT_MAP.md
* MODULE_INDEX.md
* DEPENDENCY_MAP.md

---

## 11. Testing Expectations

When adding new logic:

* Add unit tests in the tests directory.
* Mirror source directory structure.
* Ensure test coverage for critical paths.

---

## 12. Safety Rules

Do NOT:

* rewrite large parts of the codebase unnecessarily
* introduce breaking API changes
* add new external dependencies without justification

Prefer minimal, safe modifications.

---

## 13. AI Interaction Summary

AI assistants should:

* understand the architecture first
* make minimal targeted changes
* keep code modular and readable
* follow project conventions

---

## 使用建议

1. 将 `REPO_PROMPT.md` 放在仓库根目录，与 `PROJECT_MAP.md`、`AI_CONTEXT.md` 同级。
2. 在 IDE 的 AI 设置中，如果支持 **repo rules / system prompt**，可指向此文件。
3. 当项目架构变化时，及时同步更新。

## 搭配文件（推荐最小组合）

最实用的一组是：

```
AI_CONTEXT.md
PROJECT_MAP.md
MODULE_INDEX.md
DEPENDENCY_MAP.md
project_rules.md
REPO_PROMPT.md
```

这 6 个文件通常就足以让 AI 在中大型仓库里保持较稳定的改动质量。