Refactor AI documentation structure and workflows

- Deleted obsolete ADR-002: Thin Tool Adapters document.
- Updated naming-and-paths.md to clarify root entry file rules.
- Revised project-structure.md to reflect current repository shape and usage rules.
- Removed tool-entrypoints.md as it was redundant.
- Enhanced verification.md to include CI gate details and usage rules.
- Updated design-system.md and documentation.md for clarity on frontend constraints.
- Removed outdated workflows for adding backend, frontend, fullstack features, fixing bugs, and releasing.
- Updated pyproject.toml to include maintainer email.
- Deleted scripts for checking AI docs and syncing adapters as they are no longer needed.

Author: Tendo33

AGENTS.md

@@ -1,7 +1,5 @@
 # Project Agent Entrypoint
 
-<!-- Generated by scripts/sync_ai_adapters.py -->
-
 This file is the cross-tool entrypoint for this repository.
 
 ## Read order
@@ -13,6 +11,46 @@ This file is the cross-tool entrypoint for this repository.
 ## Working rules
 
 - Treat `ai_docs/` as the only detailed source of truth
-- Read `current/` before `standards/` and `workflows/`
+- Read `current/` before `standards/`, and use `reference/` for shared commands or paths
 - Keep changes minimal, typed, and explicit
 - Update docs whenever behavior, structure, scripts, adapters, or public APIs change
+
+## Execution style
+
+### Think before editing
+
+- State assumptions when they affect the implementation
+- If multiple interpretations exist, surface them instead of choosing silently
+- Prefer clarifying uncertainty before editing files
+- If a simpler approach exists, say so before implementing
+- Push back when warranted instead of mechanically following a weak approach
+- If something is unclear, stop, name the confusion, and ask
+
+### Simplicity first
+
+- Choose the smallest change that fully solves the task
+- Do not add speculative flexibility, configuration, or abstraction
+- Prefer direct fixes over framework-like restructuring
+- Do not add features beyond what was asked
+- Do not create abstractions for single-use code
+- Do not add error handling for impossible scenarios
+- If a change grows large but could be much smaller, simplify it before shipping
+
+### Surgical diffs
+
+- Touch only files and lines that relate to the request
+- Match existing project style and terminology
+- Do not improve adjacent code, comments, or formatting unless required by the task
+- Do not refactor things that are not broken
+- If you notice unrelated dead code, mention it instead of deleting it
+- Remove only the imports, variables, functions, or docs made obsolete by your own change
+- Every changed line should trace directly to the user's request
+
+### Goal-driven verification
+
+- Turn each task into a verifiable outcome
+- For non-trivial work, keep a short plan and verification path in mind before editing
+- Use `ai_docs/reference/verification.md` before claiming completion
+- Translate vague requests into concrete checks whenever possible
+- Prefer testable targets such as reproducing a bug, proving invalid input fails, or confirming behavior before and after a refactor
+- Keep looping until the requested outcome is verified, not just implemented

CLAUDE.md

@@ -1,16 +1,55 @@
 # Claude Code Project Instructions
 
-<!-- Generated by scripts/sync_ai_adapters.py -->
-
 ## Read order
 
 1. Start at [AGENTS.md](AGENTS.md)
-2. Check tool entrypoints in [ai_docs/reference/tool-entrypoints.md](ai_docs/reference/tool-entrypoints.md)
-3. Use [ai_docs/workflows/start-task.md](ai_docs/workflows/start-task.md) to route the task
+2. Use [ai_docs/START_HERE.md](ai_docs/START_HERE.md) for the current documentation layout
+3. Use [ai_docs/INDEX.md](ai_docs/INDEX.md) to route the task
 4. Run the relevant section in [ai_docs/reference/verification.md](ai_docs/reference/verification.md)
 
 ## Claude-specific notes
 
 - Use [AGENTS.md](AGENTS.md) as the shared project entrypoint
-- Route task-specific work through `ai_docs/INDEX.md` and `ai_docs/workflows/`
+- Route task-specific work through `ai_docs/INDEX.md`
 - Keep this file thin; detailed rules live in `ai_docs/`
+
+## Claude execution style
+
+### Think before coding
+
+- State assumptions explicitly when they shape the solution
+- If multiple valid interpretations exist, surface the tradeoff instead of guessing
+- If something is unclear, stop and clarify before editing
+- If a simpler approach exists, say so before implementing
+- Push back when warranted instead of following a weak approach blindly
+- Name confusion directly rather than hiding it behind implementation
+
+### Simplicity first
+
+- Implement the minimum change that solves the requested problem
+- Do not add extra features, configuration, or abstraction that was not requested
+- If a simpler solution exists, prefer it
+- Do not add abstractions for single-use code
+- Do not add speculative flexibility
+- Do not add error handling for impossible scenarios
+- If a large solution could clearly be much smaller, rewrite it before shipping
+
+### Surgical changes
+
+- Keep diffs tightly scoped to the task
+- Do not refactor adjacent code, comments, or formatting unless the request requires it
+- Clean up only the fallout caused by your own changes
+- Match existing style even when you would normally choose differently
+- If you notice unrelated dead code, mention it instead of deleting it
+- Remove only imports, variables, functions, or docs that your own changes made obsolete
+- Every changed line should trace directly to the user's request
+
+### Goal-driven execution
+
+- For multi-step tasks, keep a brief plan with a verification step for each major change
+- Prefer tests or direct checks that prove the requested outcome
+- Before declaring success, run the relevant commands in [ai_docs/reference/verification.md](ai_docs/reference/verification.md)
+- Translate vague requests into concrete, verifiable goals before implementing
+- Treat bug fixes as reproduction plus proof of fix
+- Treat refactors as behavior-preserving changes that must verify before and after
+- Keep iterating until the success criteria are verified, not merely approximated

README.md

@@ -131,7 +131,7 @@ python scripts/rename_package.py my_new_project
 脚本会同时处理：
 
 - `src/python_template/` 目录重命名
-- 文档、配置、前端文件、AI 配置中的模板名称替换
+- 文档、配置和前端文本文件中的模板名称替换
 - `frontend/package.json` 的 `name`
 - `frontend/index.html` 的 `<title>`
 
@@ -265,7 +265,7 @@ frontend/src/
 3. 在项目根目录运行 `npx getdesign@latest add linear.app`，安装对应的 `DESIGN.md`。
 4. 然后要求你的 AI assistant 在后续 UI 工作中使用项目根目录的 `DESIGN.md`。
 
-更详细的前端设计流程和约束请看 `ai_docs/standards/design-system.md` 与 `ai_docs/workflows/add-frontend-feature.md`。
+更详细的前端设计约束请看 `ai_docs/standards/design-system.md` 与 `ai_docs/standards/frontend.md`。
 
 常用命令：
 
@@ -335,21 +335,19 @@ pnpm --prefix frontend build
 2. `ai_docs/INDEX.md`
 3. `ai_docs/current/architecture.md`
 4. `ai_docs/reference/verification.md`
-5. 按任务进入 `ai_docs/current/*`、`ai_docs/standards/*`、`ai_docs/workflows/*`
+5. 按任务进入 `ai_docs/current/*`、`ai_docs/standards/*`、`ai_docs/reference/*`
 
 如果任务涉及前端 UI：
 
 - 先看 `ai_docs/standards/design-system.md`
-- 再看 `ai_docs/workflows/add-frontend-feature.md`
+- 再看 `ai_docs/standards/frontend.md`
 - 如果项目根目录已经有 `DESIGN.md`，把它和上面两份文档一起作为 UI 工作输入
 
 当前文档覆盖：
 
 - `current/`：当前真实实现
 - `standards/`：工程准则和默认约束
-- `workflows/`：任务执行流程
-- `reference/`：共享事实，例如验证命令、目录结构、工具入口
-- `decisions/`：设计决策与架构原因
+- `reference/`：共享事实，例如验证命令、目录结构和命名规则
 
 ## Release
 

ai_adapter_config.json

@@ -3,8 +3,8 @@
 ## How to use this index
 
 - 按任务场景找文档，不按文件名猜。
-- 先看 `current/` 确认当前实现，再看 `standards/` 和 `workflows/`。
-- 涉及命令、目录、工具入口时，只引用 `reference/`。
+- 先看 `current/` 确认仓库今天真实长什么样，再看 `standards/` 确认默认做法。
+- 涉及命令、目录结构、命名规则时，只引用 `reference/`。
 
 ## I want to understand the repository
 
@@ -16,45 +16,43 @@
 
 - 当前 backend 实现：[backend.md](current/backend.md)
 - backend 约束：[backend.md](standards/backend.md)
-- 推荐执行流程：[add-backend-feature.md](workflows/add-backend-feature.md)
+- 验证命令：[verification.md](reference/verification.md)
 
 ## I want to change frontend code
 
 - 当前 frontend starter：[frontend.md](current/frontend.md)
 - frontend 约束：[frontend.md](standards/frontend.md)
-- 当前设计系统：[design-system.md](standards/design-system.md)
-- 推荐执行流程：[add-frontend-feature.md](workflows/add-frontend-feature.md)
+- 视觉和交互基线：[design-system.md](standards/design-system.md)
+- 验证命令：[verification.md](reference/verification.md)
 
-## I want to change full-stack behavior
+## I want to fix a bug or review a change
 
-- 当前系统边界：[architecture.md](current/architecture.md)
-- backend 现状：[backend.md](current/backend.md)
-- frontend 现状：[frontend.md](current/frontend.md)
-- 推荐执行流程：[add-fullstack-feature.md](workflows/add-fullstack-feature.md)
+- 工程准则：[engineering.md](standards/engineering.md)
+- 文档准则：[documentation.md](standards/documentation.md)
+- 验证命令：[verification.md](reference/verification.md)
 
-## I want to fix a bug
+## I want to update scripts or docs
 
-- 统一 bug 修复流程：[fix-bug.md](workflows/fix-bug.md)
-- 验证命令：[verification.md](reference/verification.md)
+- 当前脚本现状：[scripts.md](current/scripts.md)
+- 文档写作准则：[documentation.md](standards/documentation.md)
+- 命名与路径规则：[naming-and-paths.md](reference/naming-and-paths.md)
 
-## I want to review or polish a change
+## I want to initialize or maintain the template
 
-- 工程准则：[engineering.md](standards/engineering.md)
-- 文档准则：[documentation.md](standards/documentation.md)
-- 评审流程：[review-change.md](workflows/review-change.md)
+- 包名重命名与项目名替换：[scripts.md](current/scripts.md)
+- 版本更新：[scripts.md](current/scripts.md)
+- pre-commit 初始化：[scripts.md](current/scripts.md)
+- release notes 生成：[scripts.md](current/scripts.md)
+- 无用代码扫描：[scripts.md](current/scripts.md)
+- 相关验证命令：[verification.md](reference/verification.md)
 
 ## I want to release
 
 - 当前发版方式：[release.md](current/release.md)
-- 发版流程：[release.md](workflows/release.md)
-
-## I want to update AI adapters
-
-- 工具入口清单：[tool-entrypoints.md](reference/tool-entrypoints.md)
-- 工程与文档准则：[engineering.md](standards/engineering.md)
-- 设计决策：[adr-002-tool-adapter-strategy.md](decisions/adr-002-tool-adapter-strategy.md)
+- 验证命令：[verification.md](reference/verification.md)
 
-## I want the design rationale
+## I want to update AI entry docs
 
-- 为什么 `ai_docs/` 是唯一详细事实源：[adr-001-ai-docs-source-of-truth.md](decisions/adr-001-ai-docs-source-of-truth.md)
-- 为什么 adapter 要保持轻量：[adr-002-tool-adapter-strategy.md](decisions/adr-002-tool-adapter-strategy.md)
+- 仓库结构与入口位置：[project-structure.md](reference/project-structure.md)
+- 路径与命名规则：[naming-and-paths.md](reference/naming-and-paths.md)
+- 文档准则：[documentation.md](standards/documentation.md)

ai_docs/INDEX.md

@@ -3,36 +3,29 @@
 ## When to read
 
 - 第一次进入这个仓库时先读这里。
-- 当你不确定某个任务该看哪份文档时，先回到这里。
+- 当你不确定某个任务应该看哪份文档时，先回到这里。
 
 ## What this folder is
 
 `ai_docs/` 是这个仓库给 AI 助手、自动化工具和协作者共用的唯一详细事实源。
 
-规则：
+目录：
 
-- 共享事实只在 `ai_docs/` 维护一次。
-- 任务入口文件只做路由，不重复维护完整正文。
-- 当前实现、工程准则、任务流程、共享参考、设计决策分别落在不同层。
+- `current/`：当前真实实现
+- `standards/`：默认约束、工程规则和写作准则
+- `reference/`：共享事实，例如目录结构、命名规则和验证命令
 
 ## Fast path by task
 
 - 想快速理解仓库：先读 [INDEX.md](INDEX.md)，再读 [architecture.md](current/architecture.md)。
-- 想做 backend 改动：先读 [backend.md](current/backend.md)，再到 [INDEX.md](INDEX.md) 选择 backend workflow。
-- 想做 frontend 改动：先读 [frontend.md](current/frontend.md)，再到 [INDEX.md](INDEX.md) 选择 frontend workflow。
-- 想做 full-stack 改动：先读 [architecture.md](current/architecture.md)，再到 [INDEX.md](INDEX.md) 选择 full-stack workflow。
-- 想修 bug：先到 [INDEX.md](INDEX.md) 选择 bugfix workflow。
-- 想发版：先读 [release.md](current/release.md)，再到 [INDEX.md](INDEX.md) 选择 release workflow。
-- 想更新 AI 入口文件或规则：先读 [tool-entrypoints.md](reference/tool-entrypoints.md)，再到 [INDEX.md](INDEX.md) 找 adapter 入口。
+- 想改 backend：先读 [backend.md](current/backend.md)，再读 [backend.md](standards/backend.md)。
+- 想改 frontend：先读 [frontend.md](current/frontend.md)，再读 [frontend.md](standards/frontend.md) 和 [design-system.md](standards/design-system.md)。
+- 想初始化或维护模板：先读 [scripts.md](current/scripts.md)，再到 [INDEX.md](INDEX.md) 里的模板维护入口找对应任务。
+- 想改脚本、README 或协作文档：先读 [scripts.md](current/scripts.md)，再读 [documentation.md](standards/documentation.md)。
+- 想发版：先读 [release.md](current/release.md)，再看 [verification.md](reference/verification.md)。
 
 ## Shared references
 
 - 验证命令唯一来源：[verification.md](reference/verification.md)
 - 项目结构唯一来源：[project-structure.md](reference/project-structure.md)
 - 命名与路径约定唯一来源：[naming-and-paths.md](reference/naming-and-paths.md)
-- 工具入口与适配层说明唯一来源：[tool-entrypoints.md](reference/tool-entrypoints.md)
-
-## Notes on legacy docs
-
-- 旧路径文档仍保留为兼容入口，但正文已经迁到新结构。
-- 如果看到旧文档，请按文档里的跳转说明进入新路径，不要继续在旧文档上扩写。

ai_docs/START_HERE.md

@@ -3,33 +3,36 @@
 ## When to read
 
 - 想快速理解仓库现在已经落地了什么时先读这里。
-- 想判断某项能力是“当前实现”还是“未来推荐扩展”时先读这里。
+- 想判断某项描述属于“当前实现”还是“后续扩展方向”时先读这里。
 
 ## Current truth
 
-这个仓库当前是一个面向 AI 协作的前后端模板，不是已经内建完整业务系统的脚手架。
+这个仓库当前是一个面向 AI 协作的前后端模板，而不是已经内建完整业务系统的脚手架。
 
 它已经提供：
 
 - Python 包基础设施：配置、日志、上下文、协议、模型、工具模块
 - React + Vite 前端 starter
-- 一组维护脚本和 release 流程
-- 一套给多家 AI 工具消费的入口文件和规则 adapter
-- 一套分层的 `ai_docs/` 文档系统
+- 一组仓库维护脚本和 release 流程
+- 根目录 AI 入口文件：`AGENTS.md` 和 `CLAUDE.md`
+- 一套精简后的 `ai_docs/` 文档系统
 
 它当前没有内建：
 
-- 完整的 API / service / repository / domain 目录实现
-- 完整业务数据库层
-- 真实 full-stack demo 业务流
-- 多页面前端应用或复杂状态管理
+- 完整的 HTTP API / service / repository / domain 分层实现
+- 数据库 schema、迁移或持久化层
+- 真实业务 full-stack demo
+- 多页面前端应用或复杂前端状态架构
 
 ## Subsystems
 
-- backend、frontend、scripts 和 release 的进一步阅读路径请从 `ai_docs/INDEX.md` 进入。
+- backend 的真实实现见 [backend.md](backend.md)
+- frontend 的真实实现见 [frontend.md](frontend.md)
+- scripts 的真实实现见 [scripts.md](scripts.md)
+- release 的真实实现见 [release.md](release.md)
 
 ## Shared references
 
 - 项目结构见 [project-structure.md](../reference/project-structure.md)
-- 工具入口见 [tool-entrypoints.md](../reference/tool-entrypoints.md)
+- 命名与路径规则见 [naming-and-paths.md](../reference/naming-and-paths.md)
 - 验证命令见 [verification.md](../reference/verification.md)

ai_docs/current/architecture.md

@@ -30,7 +30,7 @@
 
 - 当前模型位于 `python_template.models`
 - 对外公共导出在 `python_template.models.__init__`
-- 模板当前提供 `BaseModel`、`TimestampMixin` 和几个示例模型
+- 当前公开导出包括 `BaseModel`、`TimestampMixin`、`User`、`ApiResponse`、`PaginatedResponse`、`ConfigModel`
 
 ## Public imports and SDK usage
 
@@ -50,9 +50,10 @@
 - 当前还没有内建持久化层
 - 当前还没有按业务领域拆开的 service / repository / domain 结构
 
-这些属于后续项目扩展方向，具体约束请从 `ai_docs/INDEX.md` 进入对应 standards 和 workflows。
+这些属于后续项目扩展方向，具体做法以 standards 文档和当前代码现状为准。
 
 ## Shared references
 
+- backend 约束见 [backend.md](../standards/backend.md)
 - 项目结构见 [project-structure.md](../reference/project-structure.md)
 - 验证命令见 [verification.md](../reference/verification.md)