chore(task): archive 00-bootstrap-guidelines

2026-08-08 19:41:18 +08:00
parent b814ad42d7
commit 3405250c0f
2 changed files with 2 additions and 2 deletions
@@ -0,0 +1,144 @@
+# Bootstrap Task: Fill Project Development Guidelines
+
+**You (the AI) are running this task. The developer does not read this file.**
+
+The developer just ran `trellis init` on this project for the first time.
+`.trellis/` now exists with empty spec scaffolding, and this bootstrap task
+exists under `.trellis/tasks/`. When they want to work on it, they should start
+this task from a session that provides Trellis session identity.
+
+**Your job**: help them populate `.trellis/spec/` with the team's real
+coding conventions. Every future AI session — this project's
+`trellis-implement` and `trellis-check` sub-agents — auto-loads spec files
+listed in per-task jsonl manifests. Empty spec = sub-agents write generic
+code. Real spec = sub-agents match the team's actual patterns.
+
+Don't dump instructions. Open with a short greeting, figure out if the repo
+has any existing convention docs (CLAUDE.md, .cursorrules, etc.), and drive
+the rest conversationally.
+
+---
+
+## Status (update the checkboxes as you complete each item)
+
+- [x] Fill backend guidelines
+- [x] Fill frontend guidelines
+- [x] Add code examples
+
+## Analysis Notes
+
+- 后端当前没有数据库、迁移、持久化客户端或实际日志实现，因此移除了 `database-guidelines.md` 和 `logging-guidelines.md` 模板；相关能力出现时应先建立真实实现和对应规格。
+- 规格以 `zhixing-server/src/`、`zhixing-server/tests/`、`zhixing-web/src/`、项目 README 和 ADR 为依据，GitNexus/ABCoder 索引未在本环境中可用。
+
+---
+
+## Spec files populated
+
+
+### Backend guidelines
+
+| File | What to document |
+|------|------------------|
+| `.trellis/spec/backend/directory-structure.md` | 包结构、bounded context 和导入边界 |
+| `.trellis/spec/backend/configuration-and-runtime.md` | Settings、应用工厂和部署环境 |
+| `.trellis/spec/backend/http-api-contracts.md` | 路由组合、响应模型和同源 API 路径 |
+| `.trellis/spec/backend/error-handling.md` | 当前 FastAPI 错误行为及跨层错误传递 |
+| `.trellis/spec/backend/quality-guidelines.md` | Ruff、Pyright、pytest 及禁止模式 |
+
+
+### Frontend guidelines
+
+| File | What to document |
+|------|------------------|
+| `.trellis/spec/frontend/directory-structure.md` | Component/page/hook organization |
+| `.trellis/spec/frontend/component-guidelines.md` | Component patterns, props conventions |
+| `.trellis/spec/frontend/hook-guidelines.md` | Custom hook naming, patterns |
+| `.trellis/spec/frontend/state-management.md` | State library, patterns, what goes where |
+| `.trellis/spec/frontend/type-safety.md` | TypeScript conventions, type organization |
+| `.trellis/spec/frontend/quality-guidelines.md` | Linting, testing, accessibility |
+
+
+### Thinking guides
+
+`.trellis/spec/guides/` contains this project's code-reuse and cross-layer
+contract checks, backed by the actual API/query/UI flow.
+
+---
+
+## How to fill the spec
+
+### Step 1: Import from existing convention files first (preferred)
+
+Search the repo for existing convention docs. If any exist, read them and
+extract the relevant rules into the matching `.trellis/spec/` files —
+usually much faster than documenting from scratch.
+
+| File / Directory | Tool |
+|------|------|
+| `CLAUDE.md` / `CLAUDE.local.md` | Claude Code |
+| `AGENTS.md` | Codex / Claude Code / agent-compatible tools |
+| `.cursorrules` | Cursor |
+| `.cursor/rules/*.mdc` | Cursor (rules directory) |
+| `.windsurfrules` | Windsurf |
+| `.clinerules` | Cline |
+| `.roomodes` | Roo Code |
+| `.github/copilot-instructions.md` | GitHub Copilot |
+| `.vscode/settings.json` → `github.copilot.chat.codeGeneration.instructions` | VS Code Copilot |
+| `CONVENTIONS.md` / `.aider.conf.yml` | aider |
+| `CONTRIBUTING.md` | General project conventions |
+| `.editorconfig` | Editor formatting rules |
+
+### Step 2: Analyze the codebase for anything not covered by existing docs
+
+Scan real code to discover patterns. Before writing each spec file:
+- Find 2-3 real examples of each pattern in the codebase.
+- Reference real file paths (not hypothetical ones).
+- Document anti-patterns the team clearly avoids.
+
+### Step 3: Document reality, not ideals
+
+**Critical**: write what the code *actually does*, not what it should do.
+Sub-agents match the spec, so aspirational patterns that don't exist in the
+codebase will cause sub-agents to write code that looks out of place.
+
+If the team has known tech debt, document the current state — improvement
+is a separate conversation, not a bootstrap concern.
+
+---
+
+## Quick explainer of the runtime (share when they ask "why do we need spec at all")
+
+- Every AI coding task spawns two sub-agents: `trellis-implement` (writes
+  code) and `trellis-check` (verifies quality).
+- Each task has `implement.jsonl` / `check.jsonl` manifests listing which
+  spec files to load.
+- The platform hook auto-injects those spec files + the task's `prd.md`
+  into every sub-agent prompt, so the sub-agent codes/reviews per team
+  conventions without anyone pasting them manually.
+- Source of truth: `.trellis/spec/`. That's why filling it well now pays
+  off forever.
+
+---
+
+## Completion
+
+When the developer confirms the checklist items above are done with real
+examples (not placeholders), guide them to run:
+
+```bash
+python3 ./.trellis/scripts/task.py finish
+python3 ./.trellis/scripts/task.py archive 00-bootstrap-guidelines
+```
+
+After archive, every new developer who joins this project will get a
+`00-join-<slug>` onboarding task instead of this bootstrap task.
+
+---
+
+## Suggested opening line
+
+"Welcome to Trellis! Your init just set me up to help you fill the project
+spec — a one-time setup so every future AI session follows the team's
+conventions instead of writing generic code. Before we start, do you have
+any existing convention docs (CLAUDE.md, .cursorrules, CONTRIBUTING.md,
+etc.) I can pull from, or should I scan the codebase from scratch?"