使用AI进行项目开发

确定项目规约

项目根目录中增加 AGENTS.md, 备注 README.md 是给人看的, AGENTS.md 主要是给AI agent看的. 在这个文件中规定项目的“硬性禁区"

# Agent 开发规范

## 项目构建与测试命令
- 构建：`npm run build` 或 `mvn compile`
- 单测：`pytest tests/unit/test_xxx.py`（禁止无原因跑全量巨型测试）

## 代码架构约束
- 业务代码位于 `src/modules/`，禁止直接在 Controller 层拼接 SQL/RPC 调用。
- 修改底层 Data Model 时必须先与用户确认。

## Git & 安全规范
- 任何文件修改前，先通过 bash 执行 `git status` 确认工作区干净。
- 禁止修改 `.env` 或涉及密钥配置的文件。

已有项目引入AI的“黄金法则”

1. 会话生命周期控制（Session Management）

• 中型项目上下文增长极快。一件事归一个 Session。比如“侦察与设计”用一个 Session，“编码实现”用一个 Session，“Bug 修复”用另一个 Session。

• 当发现 Pi 开始产生幻觉或修改不相干文件时，直接 Ctrl+C 结束当前交互，清空上下文重新输入精简提示词。

2. 活用 Pi 的中间干预机制（Steering）

• Pi 在执行一连串工具调用（如读文件、改代码、跑终端）时，你可以随时按 Enter 插入一条提示信息（它会在当前 Tool 回调结束后立即读取），如果看到它找错了文件，及时打断/纠偏，不用等它全部做完。

3. 利用 Git Branch 做物理隔离

• 每次做改善工作时，建一个 agent/feature-xxx 独立分支。

• 让 Pi 在分支上折腾，所有修改只在你的主分支通过 PR 或手动 git merge 方式合入，确保绝对安全。

从零开始的项目

确定项目roadmap和阶段任务

在项目中创建 tasks 目录, 在其中设定roadmap和各个阶段任务.

your-project/
├── .tasks/
│   ├── roadmap.md          # 整体各阶段宏观规划（只读参考）
│   └── phase-01.md         # 第1阶段任务契约
│   └── phase-02.md         # 第2阶段任务契约
├── src/                    # 源码
└── README.md

其中 roadmap.md 文件明确路线图, 内容示例如下:

# 项目路线图
- [x] 阶段 0：项目初始化与目录结构搭建
- [ ] 阶段 1：核心解析引擎实现 (当前)
- [ ] 阶段 2：CLI 交互界面与参数绑定
- [ ] 阶段 3：日志与异常兜底机制

phase-01.md 阶段文件的内容示例:

# Phase 1 任务契约：核心解析引擎

## 验收标准 (Acceptance Criteria)
1. 输入符合规范的原始文本能够正确解析出结构化对象。
2. 单元测试覆盖率达到 80% 以上。

## 任务列表
- [ ] Task 1.1: 创建 `parser.py` 并定义核心数据结构 (DataClass / Struct)。
- [ ] Task 1.2: 实现基础正则匹配逻辑，提取关键字段。
- [ ] Task 1.3: 编写针对边界异常输入的防御性代码。
- [ ] Task 1.4: 编写 Pytest 单元测试并本地运行通过。

驱动AI完成任务

直接给AI下指令：“请严格按照 .tasks/phase-01.md 中的步骤推进，一次只做一个 Task，完成当前 Task 后暂停等待确认.

在已有项目中引入AI coding agent

步骤1, 完成上下文侦察(只读不写) scout

不要直接说“帮我把 X 功能改了”，而是让 Pi 先做代码调查, prompt 范例:

我们要在现有用户模块中增加『导出 PDF 报告』的功能。请不要修改任何代码，先检索 src/user/ 和 src/report/ 目录，告诉我：

目前已有的导出逻辑是怎么实现的？

哪些类/函数可以复用？

需要新增哪些文件？请列出清单。

我们可实时观察AI的思考过程和调用的 grep/find 命令，确保它定位精准。

步骤2, 制定并审核变更方案（Design Phase）

这个步骤可以由人工全权确定变更方案, 也可以让AI写出推荐的方案, 然后由人工来定稿.
下面是一个让AI整理出一个方案的提示词:

请根据刚才的调查，在 .tasks/feature-pdf-export.md 中写一份修改计划，要求包含：

涉及到修改的现有文件（及其受影响的函数）

拟新增的文件

拟采用的改动步骤（拆分为 Task 1, Task 2...）

对应的单元测试方案

AI 写好之后, 我们必须打开这个 Markdown 文件审阅并修改.

步骤3, 原子化逐步执行（Execution Phase）

要求 Pi 严格按 Task 执行，且一次只执行一个小步骤， prompt示例:

请按照 .tasks/feature-pdf-export.md 中的 Task 1 开始编码。
只修改 Task 1 指定的文件，完成之后运行单测验证，不要继续做 Task 2，等待我的命令。

在Pi完成这个task后, 人工需要审核:

1. 观察 Pi 自动运行单测的结果。

2. 通过 Pi 的终端反馈，或直接在你的 IDE 中看 git diff。

步骤4, 人工验收与合并（Verification Phase）

阶段任务（Phase）全部完成后，进入手工验收阶段：

1. 本地运行/手动测试：在本地调起服务，测试边界情况。

2. 处理偏差：若发现 Bug，不要直接在旧 Session 里无限追加长对话（避免上下文太长导致 Agent 变蠢），可使用 Pi 的 /model 切换强力模型做针对性 Bug 修复，或者恢复到上一个 Git Commit 重新调整提示词。

3. 验收归档：手工测试通过后，手动执行 git commit -m "feat: xxx" 并清理 .tasks/ 里的临时 Task 文件。