AI编程，几个核心工件写成了可直接使用的文件

1. AI 会话启动脚本：start-session.sh

这个脚本会强制让你的本地分支与最新 main 对齐，并为 AI 准备好最新的项目上下文快照。

#!/bin/bash
set -e

# ========== 配置项 ==========
MAIN_BRANCH="main"
SNAPSHOT_DIR=".ai-snapshot"
CONTEXT_SOURCE_DIR="docs/ai-context"
PROMPT_FILE=".ai-prompt.txt"
# ============================

echo "🔍 正在获取远程最新代码..."
git fetch origin $MAIN_BRANCH

# 检查是否有未提交的更改
if ! git diff-index --quiet HEAD --; then
    echo "⚠️  你有未提交的更改。建议先提交或暂存(stash)它们。"
    read -p "仍然继续？(y/n) " -n 1 -r
    echo
    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
        exit 1
    fi
fi

echo "🔄 正在将当前分支 rebase 到最新的 $MAIN_BRANCH ..."
if ! git rebase origin/$MAIN_BRANCH; then
    echo "❌ Rebase 发生冲突，请手动解决冲突后重新运行本脚本。"
    exit 1
fi

echo "📋 刷新 AI 上下文快照..."
rm -rf $SNAPSHOT_DIR
mkdir -p $SNAPSHOT_DIR
if [ -d "$CONTEXT_SOURCE_DIR" ]; then
    cp -r $CONTEXT_SOURCE_DIR/* $SNAPSHOT_DIR/
    echo "✅ 已复制上下文文档到 $SNAPSHOT_DIR"
else
    echo "⚠️  目录 $CONTEXT_SOURCE_DIR 不存在，请创建必要的上下文文档。"
fi

# 将所有快照内容合并为一个 prompt 文件
echo "你是一位精通本项目的高级开发助手。" > $PROMPT_FILE
echo "以下是当前项目的最新上下文信息，你生成的所有代码都必须严格遵循这些约定：" >> $PROMPT_FILE
find $SNAPSHOT_DIR -type f \( -name "*.md" -o -name "*.txt" -o -name "*.sql" \) -exec cat {} \; >> $PROMPT_FILE

echo "🚀 启动 AI 会话，上下文已就绪..."
# 将 prompt 文件内容作为 codex 的系统指令
# 如果 codex CLI 不支持直接传文件，可以用 cat 管道或 --instructions-file 参数（取决于具体版本）
# 这是一个通用示例，请根据你安装的 codex CLI 实际参数调整
if command -v codex &> /dev/null; then
    codex --instructions-file "$PROMPT_FILE"
else
    echo "❌ 未找到 codex 命令，请确认已安装 OpenAI Codex CLI。"
    echo "提示文件已生成：$PROMPT_FILE，可以手动粘贴给 AI 工具。"
fi

使用方式：

每个开发者在开始工作前，在自己的 feature 分支下执行 bash start-session.sh。

---

2. 自动生成变更摘要的 Git Hook

这个 hook 会在你完成一次 merge（通常是向 main 合并）后 ，强制你输入一段可读的变更摘要，并自动追加到 CHANGELOG.md，供其他开发者的 AI 读取。

文件路径：.git/hooks/post-merge （记得赋予执行权限 chmod +x）

#!/bin/bash
# 仅当合并的目标分支是 main 时才触发
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [ "$CURRENT_BRANCH" != "main" ]; then
    exit 0
fi

CHANGELOG="docs/ai-context/CHANGELOG.md"

# 获取此次合并带来的最新提交信息（仅首次父提交的差异）
MERGE_MSG=$(git log -1 --pretty=%B)
AUTHOR=$(git log -1 --pretty=%an)
DATE=$(date "+%Y-%m-%d %H:%M")

echo "📝 检测到向 main 的合并，请填写本次变更摘要（直接回车跳过）:"
echo "   (例如：修改了支付模块的退款接口，增加了 reason 字段)"
read -p "> " SUMMARY

if [ -z "$SUMMARY" ]; then
    echo "⏭️  未填写摘要，跳过 CHANGELOG 更新。"
    exit 0
fi

# 确保目录存在
mkdir -p "$(dirname "$CHANGELOG")"

# 写入带时间戳和作者的记录
{
    echo "## $DATE ($AUTHOR)"
    echo "- $SUMMARY"
    echo ""
} >> "$CHANGELOG"

echo "✅ 已更新 $CHANGELOG"

💡 如果团队使用 GitHub / GitLab，更推荐在 CI 中实现类似功能（通过 Pull Request 的合并信息自动生成）。但在初期，让合并者手工填写一句摘要，反而能保证质量。

---

3. AI 上下文文档模板

在仓库中创建 docs/ai-context/ 目录，并按以下模板维护这些文件。关键原则：每当功能合入 main，必须同步更新对应的文档。

3.1 ARCHITECTURE.md （架构与模块职责）

# 项目系统架构

## 技术栈
- 前端：React 18 + TypeScript
- 后端：Node.js + Express
- 数据库：PostgreSQL
- 缓存：Redis

## 模块划分与职责

### 用户模块 (src/user)
- 注册、登录、JWT 鉴权
- 仅通过 `IUserService` 向其他模块暴露接口

### 支付模块 (src/payment)
- 订单创建、支付回调处理
- 依赖用户模块的 `getUserById` 接口

### 公共工具 (src/shared)
- 日志、加密、统一错误类型
- 禁止在此处编写业务逻辑

## 数据流
- 前端请求 → API Gateway → 业务服务 → 数据库
- 支付回调 → 外部 Webhook → 支付模块 → 订单状态更新

3.2 API_CONTRACTS.md （接口契约）

# API 接口契约

## 用户模块
- `POST /api/login`  请求：`{ username, password }`  响应：`{ token, userId }`
- `GET /api/user/:id`  响应：`{ id, name, email }`

## 支付模块
- `POST /api/order`  请求：`{ userId, amount }`  响应：`{ orderId, payUrl }`
- `POST /api/payment/callback`  请求：`{ orderId, status }`  响应：`{ success }`

**注意：任何对上述接口的修改必须同步更新此文档并通知全员。**

3.3 CURRENT_TASKS.md （当前正在开发的功能）

# 当前并行开发任务

| 成员  | 功能分支         | 影响范围        | 预计影响文件           |
|-------|------------------|-----------------|------------------------|
| 张三  | feature/2fa      | 用户登录流程    | src/user/login.ts     |
| 李四  | feature/refund   | 支付退款逻辑    | src/payment/refund.ts |
| 王五  | feature/logger   | 全局日志        | src/shared/logger.ts  |

**请 AI 在生成代码前，先检查此表，避免修改他人正在活跃开发的文件。**

3.4 CODING_STANDARDS.md （代码规范）

# 编码规范

- 使用 TypeScript 严格模式，禁止 any 类型
- 函数必须添加 JSDoc 注释，说明参数和异常
- 错误处理：使用自定义 AppError 类，禁止直接抛字符串
- 测试：所有接口至少一个集成测试，放在 __tests__ 目录
- 命名：文件名使用 kebab-case，变量使用 camelCase

---

4. 最终目录结构建议

你们的仓库根目录最终可能看起来像这样：

project-root/
├── src/
├── docs/
│   └── ai-context/
│       ├── ARCHITECTURE.md
│       ├── API_CONTRACTS.md
│       ├── CURRENT_TASKS.md
│       ├── CODING_STANDARDS.md
│       ├── DATABASE_SCHEMA.sql
│       └── CHANGELOG.md        # 由 git hook 自动更新
├── start-session.sh             # 每个开发者根目录下
└── .git/
    └── hooks/
        └── post-merge           # 手动复制或通过 makefile 安装

---

5. 你需要做的下一步

1. 将这些文件放入仓库，并让所有成员拉取最新代码。

2. 把 start-session.sh 和 post-merge hook 分发到每个人的本地环境（可以通过 make install-hooks 自动复制）。

3. 开一个 10 分钟的短会，约定好"每天开始工作前必须先跑 start-session.sh"。

4. 监控几轮迭代，你会发现代码覆盖问题会显著下降。