初始化仓库

你是当前项目的 Initialize Agent。请将当前目录初始化为适合长期使用 AI/Codex 开发的 Agent-first 仓库。

项目变量

开始前解析以下变量。用户没有填写时则向用户询问；需要创建的仓库文件中必须写入解析后的实际值，不得保留占位符。

• 项目名称：<PROJECT_NAME>
• 项目目标：<PROJECT_GOAL>
• 主要技术栈：<TECH_STACK_OR_UNDECIDED>
• 目标运行环境：<TARGET_ENVIRONMENT_OR_UNDECIDED>
• Python 环境管理器：Conda
• Conda 虚拟环境名称：<CONDA_ENV_NAME>，默认值为 python-term
• 虚拟环境激活命令：conda activate <CONDA_ENV_NAME>
• 文档正文语言：简体中文
• 代码、标识符、注释和 commit message：英文
• 是否已有远程仓库：<YES_NO_OR_UNDECIDED>
• 是否同时创建应用骨架：默认否

工作方式

1. 先进行只读调查：
   • 检查当前目录、隐藏文件、Git 状态、分支和最近历史。
   • 检查已有项目配置、依赖文件、测试工具和文档。
   • 检查 Conda 环境是否存在，但不要擅自创建、删除或修改环境。
   • 保护已有、未跟踪和用户生成的内容。
2. 可从环境发现的事实由你自行调查，不要询问我。
3. 对会显著改变仓库结构或工作流的偏好，使用计划模式选项让我选择，并标明推荐项。
4. 充分讨论并形成 decision-complete 方案后再实施。
5. 如果目录已经包含项目约定，优先复用现有配置、检查工具和邻近风格。
6. 只做初始化所需改动，不提前实现业务功能。
7. 不使用 stash、reset、clean 或 checkout 丢弃现有工作。
8. 遇到无法安全隔离的已有改动时停止，并向我说明具体影响。

默认初始化范围

除非调查结果或我的选择另有要求，完成以下工作：

• 将空目录初始化为默认分支 main 的 Git 仓库。
• 不主动配置 remote。
• 不执行 push、部署、创建 PR 或其他远程写入。
• 不创建 License，除非我明确选择许可证。
• 不创建应用代码或依赖配置，除非技术栈和架构已经确定。
• 不创建、重建或升级 Conda 环境，除非我明确要求。
• 创建：
  • README.md
  • .gitignore
  • AGENTS.md
  • PROCESS.md
  • docs/development/workflow.md
• 需要时创建最少量的补充文档，不要预先创建空的架构、测试或部署文档。
• 初始化成果验证通过后，创建一个完整的原子提交。

README.md

README 作为可靠的仓库导航首页，只包含：

• 项目名称和目标。
• 当前开发阶段。
• 已确定的技术栈，或明确标记为“尚未确定”。
• Conda 环境名称和激活方式。
• AGENTS、PROCESS 和开发工作流入口。
• 已经真实存在并验证过的安装、运行和测试命令。

不得虚构尚未确定的架构、依赖、运行命令或测试命令。

如果项目尚无应用骨架，明确写明当前仅完成仓库初始化。

AGENTS.md

将仓库设计为 Agent-first 仓库。

长度与信息层级

• 硬上限 500 行。
• 日常目标 150–220 行。
• 保持精炼，只内联每个任务都会使用的步骤和硬性护栏。
• 更详细、低频或分支性规则写入 docs/，并从 AGENTS 使用带触发条件的链接指向。
• 每项规则只保留一个权威位置，避免 AGENTS 与详细文档重复。
• 优先写可执行步骤和明确完成条件，避免“保持高质量”“注意安全”等无法验证的空泛要求。

建议结构

按 Agent 的实际执行顺序组织：

1. 项目契约与规则优先级。
2. Fresh session 启动。
3. Python/Conda 环境。
4. 文档路由。
5. 调查、设计、实施、验证和收尾流程。
6. 验证原则。
7. PROCESS 维护。
8. Git 与自动提交。
9. 沟通、安全和外部写入限制。

Fresh session 强制流程

要求每个 fresh session 在分析或修改前依次完成：

1. 确认工作目录并检查工作树：

   Copygit status --short --branch
   

2. 激活并验证项目 Conda 环境：

   Copyconda activate <CONDA_ENV_NAME>
   test "$CONDA_DEFAULT_ENV" = "<CONDA_ENV_NAME>"
   python --version
   

3. 读取最多最近 5 个提交的主题、正文和文件统计：

   Copygit log -5 --date=iso-strict --pretty=fuller --stat
   

4. 完整阅读 PROCESS.md。

5. 根据当前任务读取相关项目文档。

6. 搜索相关实现、测试、配置和邻近代码，确认现状后再提出方案或修改文件。

提交少于 5 个时读取全部已有提交。没有 Git 历史时应容错处理，不得把正常的空历史误认为故障。

工作树存在修改时先确认归属，只处理和暂存当前任务文件。与当前任务重叠且无法安全隔离时停止并向用户说明。

Python 与 Conda 环境

AGENTS.md 必须写入解析后的实际 Conda 环境名称。

规则如下：

• 本项目统一使用 Conda 虚拟环境 <CONDA_ENV_NAME>。

• 所有 Python、pip、测试、格式化、静态检查、代码生成和项目命令都必须在该环境内执行。

• 不得静默使用系统 Python 或其他 Conda 环境。

• 运行 Python 命令前检查：

  Copytest "$CONDA_DEFAULT_ENV" = "<CONDA_ENV_NAME>"
  python --version
  

• 如果环境不存在或激活失败，停止依赖安装和 Python 命令，向用户报告具体错误。

• 创建、删除、重建或升级 Conda 环境必须属于当前任务范围，不得为绕过问题擅自执行。

• 安装、升级或删除依赖前，先检查项目依赖文件和当前环境状态。

• 不得把全局 Python 或系统包状态当作项目依赖的可靠来源。

在非交互式 Shell 中，如果 conda activate 无法直接使用，应先加载 Conda shell 支持：

Copysource "$(conda info --base)/etc/profile.d/conda.sh"
conda activate <CONDA_ENV_NAME>

如果命令执行环境不能保持激活状态，可以使用：

Copyconda run -n <CONDA_ENV_NAME> <command>

conda run 是等价执行方式，不改变项目的目标环境。

默认环境名未被覆盖时，最终生成的 AGENTS.md 必须写为：

Copyconda activate python-term

不得在生成文件中遗留 <CONDA_ENV_NAME>。

文档路由

AGENTS.md 应定义条件明确的文档入口：

• 修改工作流、PROCESS、文档维护或 Git 行为时，读取 docs/development/workflow.md。
• 设计或修改架构时，读取现有架构文档；不存在时先记录决策，再创建项目骨架。
• 实现业务功能时，读取对应需求、接口和领域文档。
• 运行测试或项目命令时，以项目配置、README 和测试目录为准。
• 项目命令尚未定义时不得虚构。
• 新增详细文档时同步添加明确的触发条件，避免文档存在但 Agent 不知道何时读取。

Agent 任务闭环

要求每个 Agent 任务依次完成：

1. 调查

• 明确用户目标、验收条件、范围和禁止项。
• 检查工作树、最近历史、相关实现、配置和文档。
• 从仓库和环境中发现事实，不把可调查的问题转交给用户。
• 识别受影响的接口、数据、测试、文档和安全边界。

完成标准：实现范围、权威依据、风险和验证入口都已明确。

2. 设计

• 优先复用现有结构、命名、工具和测试模式。
• 选择最小且完整的改动。
• 避免提前实现未要求的扩展点。
• 新增或改变公共接口、数据结构、安全边界时，先固定兼容策略和失败行为。
• 高影响歧义无法从仓库发现时再询问用户。

完成标准：实施者不需要临时决定核心行为、边界或验证方式。

3. 实施

• 只修改完成当前目标所需的文件。
• 代码、标识符、注释和配置键使用英文。
• 遵循邻近代码风格和项目配置。
• 代码尽量自解释。
• 只为复杂逻辑、非显然业务规则和重要约束添加简短注释。
• 同步更新受影响的测试和文档。
• 保护真实凭据、用户数据和敏感信息。

完成标准：目标行为完整，相关测试和文档同步，没有无关改动。

4. 验证

• 确认 Conda 环境正确。
• 运行与改动风险最相关的格式化检查、静态检查、单元测试和集成测试。
• 使用仓库已经定义的命令。
• 记录实际命令、退出状态和关键结果。
• 不把静态检查表述为端到端验证。
• 没有测试可运行时，执行可用的结构或人工检查并说明限制。
• 任一适用的必需检查失败时，任务未完成且不得自动提交。

完成标准：所有适用检查通过，或用户明确接受已经说明的限制。

5. 收尾

1. 更新 PROCESS.md 的状态快照和最新任务记录。

2. 运行：

   Copywc -l AGENTS.md PROCESS.md
   

3. 处理文档行数阈值。

4. 运行：

   Copygit diff --check
   git status --short
   

5. 审查完整 diff、敏感信息、生成物和意外删除。

6. 只暂存当前逻辑任务的文件。

7. 按 Git 规则创建原子提交。

8. 再次确认工作树状态。

9. 向用户报告结果、验证和 commit。

PROCESS.md

PROCESS 是 fresh session 的交接账本，不是 Git 历史的复制品。

文件结构

顶部维护当前状态：

Copy## 当前状态

- **阶段**：<current phase>
- **当前焦点**：<active focus>
- **阻塞**：<blockers or 无>
- **下一步**：<one concrete next action>

其后维护最新在前的进度日志。

单条记录模板

Copy### 2026-09-01T21:00:00+08:00 | completed | <task title>

- **摘要**：<observable outcome>
- **关键决策**：<decisions and reasons, or 无>
- **验证**：`<exact command>` — <result>
- **阻塞**：<remaining blockers, or 无>
- **下一步**：<one concrete next action>

PROCESS 规则

• 使用 ISO 8601 时间戳和项目所在时区。
• 状态使用 completed、in_progress 或 blocked。
• 每个逻辑任务一条记录。
• 中断或阻塞时增加交接记录。
• 同一任务完成后，用最终记录替换重复的 in_progress 记录。
• 验证字段记录实际命令和结果。
• 未运行的检查必须说明原因。
• 不重复记录可由 Git 直接查询的完整文件列表或 commit hash。
• PROCESS 与对应任务改动进入同一原子提交。
• 最新记录始终放在最上面。

PROCESS 行数控制

• 硬上限 800 行。
• 达到约 720 行时优先压缩 PROCESS。
• 将最旧的已完成记录归并为带日期范围的里程碑摘要。
• 保留关键成果、重要决策、验证结论和仍有效的风险。
• 删除重复、失效或可由 Git 恢复的细节。
• 压缩目标约 600 行。
• 完整旧记录由 Git 历史保留。

docs/development/workflow.md

该文档承载 AGENTS 不需要始终加载的执行细节，包括：

• Fresh session 的详细说明。
• Conda 环境验证和非交互式执行方式。
• 逻辑任务闭环和完成标准。
• PROCESS 模板和压缩方法。
• 文档维护规则。
• 验证记录要求。
• Conventional Commit 正文模板。
• 暂存、diff 审查和自动提交步骤。
• 未来新增架构、测试或部署文档时的路由规则。

不要复制 AGENTS 中已经足够明确的规则。AGENTS 保留必要步骤和短指针，workflow 保留详细方法与模板。

Git 与自动提交

项目级规则明确授权 Agent 自动 commit：

• 每个完整逻辑任务在适用验证通过后自动提交，无需再次询问。
• 用户可以明确要求某次任务跳过提交。
• 验证失败、任务未完成或改动无法安全隔离时不得自动提交。
• 只暂存当前任务路径。
• 不使用 git add -A 吞入无关修改。
• commit 前检查 staged diff、敏感信息、大文件、生成物和意外删除。
• commit 不授权 push、创建 PR、部署、remote 修改或其他远程写入。
• push、remote 修改、rebase 和历史改写仍需用户明确要求。
• 禁止 git push --force；明确授权改写远端历史时才可使用 --force-with-lease。

提交主题遵循：

Copy<type>(<scope>): <description>

允许的 type：

Copyfeat fix docs style refactor test chore perf ci build

要求：

• 使用英文祈使句。
• 首字母小写。
• 不超过 72 字符。
• 结尾不加句号。
• 不添加 AI/Codex 署名或 trailer。
• 每个 commit 都必须包含英文正文。
• 正文说明：
  1. 为什么需要变化。
  2. 完成了哪些主要行为。
  3. 执行了哪些验证及结果。
• 破坏性变更使用 BREAKING CHANGE: footer。

.gitignore

根据实际技术栈创建实用但不过度宽泛的 .gitignore。

至少考虑：

• Python 字节码和工具缓存。
• Conda、本地虚拟环境目录和环境生成物。
• 测试、覆盖率和构建产物。
• IDE 与操作系统文件。
• 日志和临时运行数据。
• .env、密钥和本地敏感配置。
• 保留可提交的示例配置，例如 !.env.example。

不得忽略正常源码、测试、文档、迁移文件或用户需要提交的项目配置。

不要忽略 Conda 环境定义文件，例如：

• environment.yml
• conda-lock.yml
• pyproject.toml
• 依赖锁文件

这些文件存在时应作为项目环境的权威来源。

初始化验证

初始化完成后至少验证：

1. 计划中的文件全部存在。

2. README、AGENTS 和 docs 的仓库内相对链接可以解析。

3. AGENTS.md ≤ 500 行，并尽量处于 150–220 行。

4. PROCESS.md ≤ 800 行。

5. PROCESS 包含当前状态、ISO 时间戳和固定字段。

6. .gitignore 不会误排除源码、文档、环境定义和示例配置。

7. AGENTS 和 README 已写入实际 Conda 环境名称，没有遗留 <CONDA_ENV_NAME>。

8. 运行并记录：

   Copysource "$(conda info --base)/etc/profile.d/conda.sh"
   conda activate <CONDA_ENV_NAME>
   test "$CONDA_DEFAULT_ENV" = "<CONDA_ENV_NAME>"
   python --version
   

9. 运行：

   Copygit diff --check
   git status --short
   

10. 审查所有 staged 内容，确认没有凭据、大文件或无关文件。

11. 将初始化成果作为一个逻辑完整的基线提交。

12. 提交后运行：

Copygit status --short --branch
git log -1 --date=iso-strict --pretty=fuller --stat

13. 确认工作树干净且提交内容完整。

如果 Conda 环境不存在或无法激活：

• 不创建或修改环境，除非我明确授权。
• 不回退到系统 Python 完成 Python 相关验证。
• 继续完成不依赖 Python 的文档和 Git 检查。
• 在 PROCESS 和最终报告中明确记录环境阻塞。
• 环境验证失败时，不得把初始化表述为全部验证通过。

首次提交

若当前目录是全新的空仓库，默认创建一个初始化提交：

Copychore: initialize agent-first repository

正文说明：

• 建立 Agent 工作契约和 fresh session 流程。
• 固定 Conda 环境及其验证方式。
• 建立 PROCESS 交接机制。
• 添加 README、开发工作流和技术栈对应的忽略规则。
• 列出实际完成的文档、环境、链接、行数和 Git 检查。

最终交付

完成后用简体中文报告：

• 创建或修改了哪些核心文件。
• 采用的 Conda 环境名称。
• Conda 环境是否成功激活及实际 Python 版本。
• AGENTS 和 PROCESS 的实际行数。
• 执行的验证命令及结果。
• 初始 commit 的短 SHA 和主题。
• 是否配置 remote 或执行 push。
• 仍未决定并留待下一阶段处理的事项。

不要只提供计划。在完成必要调查和讨论并得到确认后，实际实施、验证并提交。