标准项目结构规划方案

基于 llms-full.txt 中 14 讲 + 资源模板 + OpenAI 高级仓库模板的方法论提炼，我为你规划了一个两层标准项目结构：最小版（对应讲座 1-12 的核心 harness）和进阶版（对应 OpenAI 高级模板，适用于长期大型项目）。

一、设计原则（从课程中提炼）

课程贯穿一致的 7 条核心原则直接决定了目录结构：

#	原则	出处	对结构的影响
1	仓库是唯一事实来源	第 3 讲	所有决策、状态、约束必须以文件形式存在仓库里
2	入口文件是路由器，不是百科全书	第 4 讲	AGENTS.md/CLAUDE.md 控制在 50-200 行，详细规则拆到专题文档
3	知识靠近代码	第 3 讲	模块级文档放在对应代码目录旁，不集中堆在根目录
4	初始化与实现分离	第 6 讲	第一个会话只搭基础设施，不写业务代码
5	WIP=1 + 功能清单原语	第 7、8 讲	feature_list.json 是调度/验证/交接的唯一权威
6	干净状态五条件	第 12 讲	每次会话退出前必须满足：构建通过、测试通过、进度已记录、临时工件已清理、启动路径可用
7	可观测性双层	第 11 讲	运行时信号（日志/追踪） + 过程工件（冲刺合同/评分标准）

二、最小标准项目结构（推荐起点）

适用于大多数中小型项目，对应讲座 1-12 的核心 harness：

my-project/
├── AGENTS.md                      # 入口路由（50-200 行）：项目概览、启动命令、硬约束、专题文档索引
├── CLAUDE.md                      # Claude Code 专用入口（可选，与 AGENTS.md 内容一致或互为补充）
├── init.sh                        # 标准启动脚本：装依赖、跑测试、验证基线
├── feature_list.json              # 功能清单原语：id + behavior + verification + state
├── claude-progress.md             # 会话进度日志：当前已验证状态、会话记录、下一步
├── session-handoff.md             # 会话交接模板（较长会话可选）
├── clean-state-checklist.md       # 干净状态五条件检查清单
├── evaluator-rubric.md            # 评审评分表（正确性/验证/范围/可靠性/可维护性/交接）
├── Makefile                       # 标准化操作命令：setup / test / lint / check / dev
├── .gitignore
├── README.md                      # 人类入口（项目介绍、快速开始）
│
├── docs/                          # 专题文档（按需展开，第 4 讲原则）
│   ├── api-patterns.md            # API 设计规范（添加端点时读）
│   ├── database-rules.md          # 数据库操作约束（涉及 DB 时读）
│   ├── testing-standards.md       # 测试标准（写测试时读）
│   └── architecture.md            # 架构决策记录（可选，小项目可合并进 AGENTS.md）
│
├── src/                           # 源代码
│   ├── api/
│   │   ├── ARCHITECTURE.md        # 模块级架构（知识靠近代码，第 3 讲原则）
│   │   └── ...
│   ├── db/
│   │   ├── CONSTRAINTS.md         # 数据库硬约束
│   │   └── ...
│   └── ...
│
├── tests/                         # 测试文件
├── scripts/                       # 运维脚本（部署、数据迁移等）
└── .github/                       # CI 配置（可选）
    └── workflows/

各文件职责详解

AGENTS.md（入口路由，第 2、4 讲核心）

# AGENTS.md

## 项目概览
[一句话说清这是什么：技术栈 + 主要功能]
例：Python 3.11 FastAPI 后端，PostgreSQL 15 数据库，提供电商 API。

## 快速开始
- 安装：`make setup`
- 测试：`make test`
- 完整验证：`make check`
- 启动开发服务器：`make dev`

## 硬约束（不超过 15 条）
- 所有 API 必须走 OAuth 2.0 认证
- 所有数据库查询必须用 SQLAlchemy 2.0 语法
- 所有 PR 必须通过 pytest + mypy --strict + ruff check
- 一次只做一个功能（WIP=1）
- 没有可运行证据时，不要声称完成

## 必需文件
- `feature_list.json`：功能状态的唯一事实来源
- `claude-progress.md`：会话进度和当前已验证状态
- `init.sh`：统一的启动与验证入口
- `session-handoff.md`：较长会话可选的交接摘要

## 工作规则
- 每轮会话开始时：pwd → 读 progress → 读 feature_list → git log → ./init.sh → smoke test
- 一次只做一个功能，完成后才能开始下一个
- 不要因为"代码已经写了"就把功能标记为完成
- 优先依赖仓库里的持久化文件，而不是聊天记录

## 完成定义
一个功能只有在以下条件都满足时才算完成：
- 目标行为已经实现
- 要求的验证真的跑过
- 证据记录在 feature_list.json 或 claude-progress.md
- 仓库仍然能按标准启动路径重新开始工作

## 收尾
结束会话前：
1. 更新 claude-progress.md
2. 更新 feature_list.json
3. 记录仍未解决的风险或 blocker
4. 在工作处于安全状态后，用清晰的提交信息提交
5. 保证下一轮会话可以直接运行 ./init.sh

## 专题文档（按需阅读，不要一次全读）
- API 设计规范 (docs/api-patterns.md) — 添加新端点时必读
- 数据库操作约束 (docs/database-rules.md) — 涉及数据库修改时必读
- 测试标准 (docs/testing-standards.md) — 编写测试时参考

feature_list.json（功能清单原语，第 8 讲核心）

{
  "version": 1,
  "features": [
    {
      "id": "F01",
      "behavior": "POST /api/auth/register with {email, password} returns 201 and JWT",
      "verification": "curl -X POST http://localhost:3000/api/auth/register -H 'Content-Type: application/json' -d '{\"email\":\"test@example.com\",\"password\":\"123456\"}' | jq .status == 201",
      "state": "passing",
      "evidence": "commit abc123, test output log 2024-01-15"
    },
    {
      "id": "F02",
      "behavior": "POST /api/auth/login with valid credentials returns 200 and JWT",
      "verification": "curl -X POST http://localhost:3000/api/auth/login -d '...' | jq .status == 200",
      "state": "active",
      "evidence": null
    },
    {
      "id": "F03",
      "behavior": "GET /api/products returns paginated product list",
      "verification": "curl http://localhost:3000/api/products?page=1 | jq '.data | length == 20'",
      "state": "not_started",
      "evidence": null
    }
  ]
}

状态机：not_started → active → passing（唯一可逆路径：验证失败回 active）门控规则：agent 不能直接改 passing，只能由验证命令执行结果决定

claude-progress.md（进度日志，第 5、6 讲核心）

# 进度日志

## 当前已验证状态
- 仓库根目录：/path/to/project
- 标准启动路径：./init.sh
- 标准验证路径：make check
- 当前最高优先级未完成功能：F02（用户登录）
- 当前 blocker：无

## 会话记录

### Session 001
- 日期：2024-01-15
- 本轮目标：完成 F01（用户注册）
- 已完成：F01 通过所有验证
- 运行过的验证：make check（全绿）
- 已记录证据：commit abc123, test output log
- 提交记录：abc123 "feat: implement user registration (F01)"
- 已知风险或未解决问题：无
- 下一步最佳动作：开始 F02（用户登录）

### Session 002
- 日期：[待填]
- 本轮目标：
- 已完成：
- ...

init.sh（标准启动脚本，第 6 讲核心）

#!/usr/bin/env bash
set -euo pipefail

echo "=== 初始化检查 ==="
pwd

echo "=== 安装依赖 ==="
# 根据项目实际情况替换
# pip install -r requirements.txt
# npm install

echo "=== 运行测试 ==="
# make test
# pytest tests/ -x
# npm test

echo "=== 完整验证 ==="
# make check

echo "=== 基线状态 ==="
echo "Git HEAD: $(git rev-parse HEAD)"
echo "Branch: $(git branch --show-current)"
echo "Uncommitted changes: $(git status --porcelain | wc -l) files"

echo "=== init.sh 完成 ==="

clean-state-checklist.md（第 12 讲核心）

# 干净状态检查清单

每次会话结束前逐项确认：

- [ ] 标准启动路径仍然可用（./init.sh 能跑通）
- [ ] 标准验证路径仍然可运行（make check 全绿）
- [ ] 当前进度已经记录到 claude-progress.md
- [ ] 功能状态真实反映了 passing 和未验证的边界（feature_list.json）
- [ ] 没有任何半成品步骤处于未记录状态
- [ ] 下一轮会话无需人工修复即可继续

evaluator-rubric.md（第 11 讲核心）

# 评审评分表

在实现完成后、正式验收前，用这张表做一次评审。

| 维度 | 问题 | 分数 (0-2) | 备注 |
|------|------|-----------|------|
| 正确性 | 实现出来的行为是否符合目标功能？ | | |
| 验证 | 要求的检查是否真的跑过，并留下证据？ | | |
| 范围纪律 | 这一轮是否基本保持在选定功能范围内？ | | |
| 可靠性 | 结果是否能在重启或重跑后继续工作？ | | |
| 可维护性 | 代码和文档是否清楚到足以交给下一轮会话？ | | |
| 交接准备度 | 新会话是否能只靠仓库内工件继续推进？ | | |

## 结论
- [ ] Accept
- [ ] Revise
- [ ] Block

## 后续动作
- 缺失的证据：
- 必须补的修复：
- 下次复审触发条件：

session-handoff.md（第 5 讲核心）

# 会话交接

## 当前已验证
- 现在明确可用的部分：
- 这轮实际跑过的验证：

## 本轮改动
- 新增了哪些代码或行为：
- 基础设施或 harness 发生了哪些变化：

## 仍损坏或未验证
- 已知缺陷：
- 未验证路径：
- 下一轮会话需要注意的风险：

## 下一步最佳动作
- 最高优先级未完成功能：
- 为什么它是下一步：
- 什么结果才算 passing：
- 这一步中哪些东西不要动：

## 命令
- 启动命令：
- 验证命令：
- 定向调试命令：

Makefile 模板

.PHONY: setup dev test lint check clean

setup:
	# 安装依赖、配置环境
	# pip install -r requirements.txt
	# npm install

dev:
	# 启动开发服务器
	# uvicorn src.main:app --reload
	# npm run dev

test:
	# 运行测试
	# pytest tests/ -x
	# npm test

lint:
	# 代码风格检查
	# ruff check src/
	# mypy src/ --strict
	# npm run lint

check: test lint
	# 完整验证 = 测试 + lint，这是 AGENTS.md 里引用的"标准验证路径"

clean:
	# 清理临时文件
	# find . -type d -name __pycache__ -exec rm -rf {} +
	# rm -rf .pytest_cache

三、进阶项目结构（OpenAI 高级模板，对应大型长期项目）

当项目进入长期维护、多 agent 并发、需要质量追踪时，在最小版基础上扩展：

my-project/
├── AGENTS.md                      # 入口路由（保持简短）
├── ARCHITECTURE.md                # 系统顶层地图（领域/分层/依赖规则）
├── init.sh
├── feature_list.json
├── claude-progress.md
├── Makefile
│
├── docs/
│   ├── PRODUCT_SENSE.md           # 产品判断：主要用户、核心痛点、质量门槛
│   ├── QUALITY_SCORE.md           # 质量评分：A/B/C/D 评级，按产品领域和架构层
│   ├── RELIABILITY.md             # 运行信号：bootstrap/verify/health check/黄金旅程
│   ├── SECURITY.md                # 安全规则：secrets/不可信输入/外部动作
│   ├── FRONTEND.md                # UI 约束：设计系统、可访问性检查
│   ├── PLANS.md                   # 计划生命周期规则
│   ├── DESIGN.md                  # 设计文档入口（路由到 docs/design-docs/）
│   │
│   ├── design-docs/
│   │   ├── index.md               # 设计文档索引（Accepted/Proposed/Deprecated）
│   │   └── core-beliefs.md        # agent-first 运行信念与持久项目规范
│   │
│   ├── exec-plans/
│   │   ├── active/                # 当前正在执行的计划（一次一个清晰当前步骤）
│   │   ├── completed/             # 已完成但保留上下文的计划
│   │   └── tech-debt-tracker.md   # 延期处理的债务与 follow-up
│   │
│   ├── product-specs/
│   │   ├── index.md               # 当前有效的用户可见行为规格
│   │   └── new-user-onboarding.md # 示例：新用户引导流程
│   │
│   └── generated/                 # 生成物（db-schema、API 文档等）
│       └── db-schema.md
│
├── src/
│   ├── api/
│   │   ├── ARCHITECTURE.md        # 模块级架构
│   │   └── ...
│   ├── db/
│   │   ├── CONSTRAINTS.md
│   │   └── ...
│   └── ...
│
├── tests/
├── scripts/
└── .github/workflows/

进阶版新增文件职责

文件	对应讲座	作用
ARCHITECTURE.md	第 3 讲	系统顶层地图：领域、分层、依赖规则、横切接口
docs/PRODUCT_SENSE.md	第 11 讲	产品判断：主要用户、核心痛点、可接受质量门槛
docs/QUALITY_SCORE.md	第 12 讲	质量评分追踪：A/B/C/D 评级，按产品领域和架构层，带变更历史
docs/RELIABILITY.md	第 11 讲	运行信号：bootstrap/verify/health check/黄金旅程/可靠性规则
docs/SECURITY.md	OpenAI 模板	安全规则：secrets、不可信输入、外部动作、依赖评审
docs/PLANS.md	OpenAI 模板	执行计划规则：何时创建、放哪、最少包含什么
docs/exec-plans/active/	OpenAI 模板	当前计划（每个文件一个计划）
docs/exec-plans/completed/	OpenAI 模板	已完成计划（保留历史上下文）
docs/exec-plans/tech-debt-tracker.md	第 12 讲	技术债跟踪：延期处理的债务
docs/design-docs/	第 3 讲	设计决策记录（ADR）
docs/product-specs/	第 8 讲	用户可见行为规格（验收标准）
docs/generated/	OpenAI 模板	生成物（db-schema、API 文档），不手改

四、初始化流程（第 6 讲）

第一个会话只做初始化，不写业务代码。产出五个工件：

可运行的环境 — make setup 成功
可验证的测试框架 — 至少一个示例测试通过
启动就绪清单文档 — 写在 claude-progress.md 里
任务分解 — feature_list.json 至少 3 个功能项
干净的 baseline commit — git 提交作为检查点

初始化验收清单

## 初始化验收清单
- [ ] make setup 从零开始能成功
- [ ] make test 至少有一个测试通过
- [ ] 新的 agent 会话能只看仓库回答"怎么跑"和"怎么测"
- [ ] feature_list.json 存在且有至少 3 个任务
- [ ] 所有内容已提交到 git

五、会话循环（每轮会话的固定流程）

对应第 6 讲的”编码代理开工流程”和第 12 讲的”干净状态”：

开工流程（每轮会话开始）

pwd # 确认在正确目录
读 claude-progress.md # 恢复持久状态
读 feature_list.json # 选择最高优先级未完成功能
git log --oneline -5 # 看最近提交
./init.sh # 标准化启动
跑基础 smoke test # 确认基线没坏
如果基线已坏，先修基线 # 不在坏状态上叠新功能
选择一个未完成功能，WIP=1 # 只围绕它工作

收尾流程（每轮会话结束）

跑 make check # 验证全绿
更新 claude-progress.md # 记录进度
更新 feature_list.json # 更新功能状态
清理临时工件 # 删 debug 日志、TODO 注释
跑 clean-state-checklist # 逐项确认
git commit # 提交干净状态
必要时写 session-handoff.md # 较长会话才需要

六、Loop Engineering 扩展（第 13 讲，可选）

当项目成熟后，可把上述手动流程升级为自动循环：

my-project/
├── .agent/
│   ├── goal-template.md        # /goal 命令模板
│   ├── loop-state.md           # 循环状态：目标、停止条件、当前迭代
│   ├── maker-prompt.md         # 生成者 prompt
│   ├── checker-prompt.md       # 评估者 prompt（独立于生成者）
│   └── automations/            # 自动化触发器
│       ├── timer.md            # 定时循环
│       └── file-watch.md       # 文件变化触发

七、选择建议

项目规模	推荐结构	理由
原型/POC/小工具	最小版，甚至只用 AGENTS.md + init.sh	第 2 讲：先有反馈子系统，投入产出比最高
中型项目（1-3 万行）	最小版完整结构	第 3-12 讲全部适用
长期维护的大型项目	进阶版	需要 QUALITY_SCORE.md、PLANS.md、RELIABILITY.md 追踪演化
多 agent 并发项目	进阶版 + Loop 扩展	需要隔离（第 3 讲 ACID）和自动化循环（第 13 讲）

八、关键注意事项（从课程失败案例中提炼）

不要一上来就用进阶版 — 第 2 讲的团队从 README → AGENTS.md → 加验证命令 → 加进度文件，四次迭代把成功率从 20% 提升到 100%。循序渐进。
AGENTS.md 不要超过 200 行 — 第 4 讲：超过 200 行就开始挤占上下文预算，关键约束会被”中间迷失”。
feature_list.json 是原语，不是备忘录 — 第 8 讲：它必须机器可读、状态由验证门控、agent 不能自己改 passing。
init.sh 必须幂等 — 第 6 讲：无论跑多少次结果一样，失败时重跑也安全。
每条指令标明来源、适用条件、过期条件 — 第 4 讲：像管理代码依赖一样管理指令，定期审计删除过时条目。
干净状态五条件缺一不可 — 第 12 讲：构建通过、测试通过、进度已记录、临时工件已清理、启动路径可用。
知识靠近代码 — 第 3 讲：src/api/ARCHITECTURE.md 比根目录一个 500 行的全局文档有用得多。