开发定位与文档维护
文档与代码使用同一 Git 版本，不按日期复制成多个相互竞争的说明。新增行为时更新其权威主题；删除或替换行为时直接改写／删除失效说明。文档中的当前契约须以实现为准；设计方向单独标明，历史背景需要时查 Git 历史。
开始修改前
从 文档索引 按问题查到主题，再进入对应目录 README 找源文件。工作区边界见 架构；本地禁测、远端验证与结果边界见 验证。本地工作约定若有额外限制也须遵守；AGENTS.md 自身保持本地忽略，不将个人环境说明当成公开项目文档。
什么写到哪里
| 内容 | 唯一主要位置 | 同步入口 |
|---|---|---|
| 目录职责、直接子文件／子目录、常见修改位置 | 该目录 README.md | 父目录 README |
| 各 crate 的依赖方向和系统边界 | architecture/README | 根 README、docs 索引摘要 |
| 解释执行、资源修订／依赖锁、解释器升级与缓存方向 | execution-and-versions.md | 根 README、架构、reader／frontend／bytecode、运行与交接 |
| 对象头、句柄、引用协议与 GC 算法 | objects.md | objects/src 文件表 |
| Number、String、Dict、Cell、函数环境和异常数据 | builtins.md | objects/src、objects/tests 与 core/tests 文件表 |
| lexer 前的输入适配、SourceUnit 与来源诊断 | reader.md | frontend 的 reader／source、CLI 与读取检查 |
| Token、lexer.peg 词法／grammar.peg 语法规则、AST 与源码诊断 | frontend.md | frontend 源码／测试／样例和 CLI |
| AST 节点／根模式、ASDL 生成、Visitor、位置与 JSON／编辑器接口 | ast.md | Endor.asdl、生成器、生成产物与 AST／CLI 检查 |
| 名称／作用域、源码编译、代码装载与执行示例 | compiler.md | compiler 源码／检查／示例、CLI 与运行指南 |
| 指令编码、栈效果、调用协议与执行限制 | bytecode.md | instruction／code／frame／eval 文件职责 |
| 地区与文本编码边界 | text-encoding.md | 配置主题与实际 I/O 入口 |
| VM／帧／对象的创建、错误退出与销毁 | lifecycle.md | 对象与字节码主题链接 |
| 环境变量、默认值、优先级、UTF-8、locale 和配置边界 | configuration.md | 相关 crate README 链接 |
| 检查入口、覆盖范围、结果边界 | validation.md | 各 tests README |
| 不可变研究表、聊天导出、临时脚本或构建产物 | 工作区外输出或忽略目录 | 不作为当前项目契约、不提交研究 HTML |
相同规则不要整段复制到多个 README。局部 README 解释本地内容并指向全局契约；全局主题用链接定位实现，不再维护第二份完整源文件表。
每次修改时同步
- 新增、删除、重命名文件或目录：更新本目录和父目录 README 的文件表；新增受版本管理目录必须有 README。该规则不覆盖 .git、target、data、work、outputs 或其他忽略产物。
- 修改 API、默认值、所有权、操作码或错误处理：同时修改上表对应主题、示例与相关检查；区分已实现行为和未来设计。
- 改主题路径：修复仓库所有内部链接，更新 docs 总索引；失效旧页直接删除，不长久保留一份旧契约。
- 改引擎验证配置：同步验证主题和脚本 README；宿主配置与部署由各宿主仓库维护。
- 检查链接、目录覆盖、旧路径和差异空白；仅在指定远端运行行为测试。没有查询 CI 结果就写未核实，不能继承上次通过的结论。
不是每次提交都要给所有文档改日期或复制版本号；只有相关内容发生变化时更新相应文档。提交及代码审查描述说明目的和验证，文档保留长期可查询的当前行为。
当前实现边界
Objects 保持零依赖；Core 仅依赖本地 Objects，负责 VM、执行帧和求值循环。两者不引入 Python type／元类、源码前端或宿主库。句柄构造保持私有；非法句柄检查放堆内部单元测试，不能为测试开放非法构造器。容器更新须经过 ObjectStore 的引用事务，Vm 方法只委托；call／execute 对象结果持有根，借用读取仍须由使用方按需 retain。
Rust 实现依赖模块可见性、trait 和 rustfmt，不照搬 CPython C 符号命名规范。Objects 的对象定义与 ObjectStore 导出集中在 objects/src/lib.rs；Core 的 VM 导出与既有对象类型重导出集中在 core/src/lib.rs，Frontend 导出集中在 frontend/src/lib.rs，内部协作用 pub(crate) 或私有方法区分。当前基础源码解析契约在 frontend.md，尚无完整 Endor 源码风格规范或通用配置框架。
Endor 是由平台解释执行的语言，字节码生成是内部准备步骤。资源版本属于平台元数据，具体 URI 与持久化协议尚未定稿，不提前写进业务语法；首版暂不要求持久化字节码缓存，详见 执行与版本模型。
AST 节点以 frontend/Endor.asdl 为唯一来源，Rust 类型／遍历器和 TypeScript／JSON Schema 为提交到 Git 的生成产物，不直接编辑；通过 scripts/generate_ast.py --write 更新，--check 做静态同步检查。生成器行为测试仅在指定远端执行。
独立 Frontend 提供阅读器、lexer/parser 和 ASDL AST；Compiler 已完成模块／函数名称分析、局部槽布局、最小字节码生成及代码装载。源码闭包、数值算术、迭代器等指令、类型检查与云服务机制仍待实现；语法可继续调整，范围见 编译契约。
导出与迁移
旧 outputs 正文已融合入 runtime，输出目录已移除。以后只维护仓库正文，不保留同文入口文件；CPython 284 项研究 HTML／Markdown 和早期报告位于本地忽略的 work/research，不上传 Git。交接入口见 handoff.md。
旧平铺路径 docs/architecture.md、development.md、endor-object.md、endor-builtins.md、bytecode-vm.md、validation.md 已由新的多层主题替代；当前入口以 文档索引 为准。