AGENTS.md：Codex 项目说明书

AGENTS.md 是项目长期上下文。
AGENTS.md 是工作边界和验收标准。
AGENTS.md 是把重复反馈变成下次默认行为的地方。

如果你已经对 Codex 说过两次，而且以后还会继续说，就考虑写进 AGENTS.md。

Codex 从项目根目录走到当前工作目录，按顺序合并沿途的指导；发生冲突时，更靠近当前工作目录的规则优先。

# AGENTS.md

## Project Overview

This repository is for ...

## Commands

- Install: ...
- Dev: ...
- Test: ...
- Build: ...

## Rules

- ...

## Verification

- ...

## Final Output

- Summarize changed files.
- List commands run and results.
- Note remaining risks.

AGENTS.md 只写“每次都希望 Codex 记住”的东西。

请先只读扫描这个项目，不要改文件。

目标：
帮我准备一份 AGENTS.md 初稿。

请重点看：
- 项目是什么类型。
- 主要目录和入口。
- package.json / README / 配置文件里的命令。
- 测试、lint、build、部署方式。
- 可能需要长期写给 Codex 的项目规则。

输出：
- 项目地图。
- 建议写进 AGENTS.md 的规则。
- 不确定的问题。

# AGENTS.md

## Project Overview

## Repository Map

## Commands

## Working Rules

## Verification

## Final Response

codex --sandbox read-only --ask-for-approval never "Summarize the current instructions."

codex --cd services/payments --sandbox read-only --ask-for-approval never "Show which instruction files are active."

请只读检查当前项目，告诉我如果要新增一篇博客文章，应遵守哪些分类、标签、图片和发布规则。
不要改文件。

# Blog Agent Guide

This repository is for a personal blog: {{BLOG_URL}}.

## Blog Positioning

- Write to leave a useful trail for future self and readers.
- Main topics: technical practice, AI tools, finance/investing notes, reading notes, and personal reflections.
- Prefer concrete experience, examples, and decisions over slogans.

## Voice

- Write primarily in Chinese unless the post itself needs English.
- Tone: calm, pragmatic, candid.
- Avoid marketing copy and hollow inspiration.
- Use first-person experience when it adds signal.
- Do not copy sentences or structure from reference blogs.

## Content Taxonomy

Each post should have exactly one primary category.

Allowed categories:

- AI 与智能体
- 工程实践
- 金融投资
- 阅读笔记
- 个人随笔
- 工具与效率
- 项目记录

Use 3-7 specific tags per post.
Avoid template/imported categories unless the content truly belongs there.

## Frontmatter

Use this shape for new Markdown posts:

```yaml
---
title: ""
date: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
draft: true
summary: ""
category: "AI 与智能体"
tags: ["Codex", "Agent", "工作流"]
series: ""
---
```

## Writing Rules

- Start each tutorial with the problem it solves.
- For technical posts, include commands, versions, errors, and final working state when relevant.
- For AI posts, verify current product and API facts against official sources.
- For finance posts, separate facts from personal judgment and avoid personalized investment advice.
- End with a useful checklist, next step, or remaining uncertainty.

## Image Rules

- Use images only when they clarify structure or workflow.
- Prefer light, readable diagrams for tutorial posts.
- Do not use decorative dark images when the reader needs to understand a process.

## Safety

- Do not overwrite unpublished drafts or personal notes.
- Do not publish or deploy unless explicitly asked.
- Do not store passwords, tokens, or private keys in content files.

## Verification

Before saying a post is ready:

- Check title, summary, category, tags, series.
- Check links and images.
- Check whether the reader can take away a concrete template, checklist, or exercise.
- Note any facts that still need verification.

# Frontend Agent Guide

## Project Overview

This is a frontend application built with ...
Primary users are ...

## Repository Map

- `src/app` or `pages`: routes and page-level components.
- `src/components`: shared UI components.
- `src/lib`: data fetching, utilities, and client helpers.
- `src/styles`: global styles and theme tokens.
- `public`: static assets.

## Commands

- Install: `pnpm install`
- Dev server: `pnpm dev`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`
- Build: `pnpm build`

Verify command names against `package.json` before running them.

## UI Rules

- Reuse existing components and design tokens.
- Do not add a new UI library without explaining why.
- Keep interactive states complete: loading, empty, error, disabled.
- Check responsive behavior on desktop and mobile when editing layout.
- Avoid changing unrelated pages during a focused task.

## Data And API Rules

- Preserve existing API contracts unless the task explicitly changes them.
- Keep error handling visible to users.
- Do not hardcode production URLs or secrets.

## Verification

Before finishing:

- Run the relevant lint/typecheck/build command if available.
- For visual changes, capture or inspect the affected viewport.
- Explain any command that could not be run.

## Final Response

Report:

- Changed files.
- User-visible behavior change.
- Verification commands and results.
- Remaining risks or follow-up work.

# Backend Agent Guide

## Project Overview

This service handles ...
Primary runtime: ...
Database / queue / cache: ...

## Repository Map

- `src/routes` or `controllers`: API entry points.
- `src/services`: business logic.
- `src/db` or `migrations`: database schema and migrations.
- `src/lib`: shared utilities.
- `tests`: automated tests.

## Commands

- Install: ...
- Test: ...
- Lint: ...
- Typecheck: ...
- Run locally: ...

Discover exact commands from README, Makefile, package manager files, or CI config before inventing commands.

## Engineering Rules

- Keep API compatibility unless the task explicitly asks for a breaking change.
- Validate inputs at the boundary.
- Handle errors explicitly; do not swallow exceptions silently.
- Prefer small, reviewable changes.
- Add or update tests for behavior changes.

## Data Safety

- Do not run destructive database commands without explicit approval.
- Do not delete migrations or rewrite applied migrations.
- Do not touch production credentials.
- For schema changes, explain migration and rollback impact.

## Verification

- Run targeted tests first, then broader checks if the change touches shared behavior.
- If tests require services that are not available locally, explain what was not verified.
- For bug fixes, include the reproduction path and why it no longer fails.

## Final Response

Include:

- Root cause when fixing a bug.
- Changed files.
- Tests run.
- Data or migration risk.
- Any manual verification still needed.

repo/
  AGENTS.md
  apps/web/AGENTS.md
  services/billing/AGENTS.override.md
  content/blog/AGENTS.md

services/payments/AGENTS.override.md

# Payments Override

## Safety

- Do not rotate API keys.
- Do not run payment migration commands.
- Do not change webhook signature verification without explicit approval.

## Verification

- Use `make test-payments` for payment logic changes.
- Include idempotency and retry behavior in the final risk note.

AGENTS.override.md 应该少而明确。

同一个问题出现两次，就写回 AGENTS.md。
三个月没被用到的规则，就考虑删掉。

请 review 当前 AGENTS.md，不要改文件。

重点检查：
- 是否有过时命令。
- 是否有无法验证的空话。
- 是否有一次性任务被写成长期规则。
- 是否遗漏项目运行、测试、构建、发布边界。
- 是否有可能冲突的规则。
- 是否太长，应该拆到子目录或 Skill。

输出：
- 必须修改。
- 建议修改。
- 可以保留。
- 建议移动到 Prompt / config / rules / Skill 的内容。

请根据当前 AGENTS.md，帮我检查新建一篇博客文章前需要遵守哪些规则。
不要改文件。