chore: add AGENTS.md, tasks/todo.md, and tasks/lessons.md for workflow management
This commit is contained in:
179
AGENTS.md
Normal file
179
AGENTS.md
Normal file
@@ -0,0 +1,179 @@
|
||||
# AGENTS.md
|
||||
|
||||
This file constrains future work in this repository. Follow it for all non-trivial changes.
|
||||
|
||||
## Repository Snapshot
|
||||
|
||||
- Root purpose: `managed-portal` is a standalone management portal for managed services and web devices.
|
||||
- Backend: Go service under `cmd/managed-portal` and `internal/`.
|
||||
- Frontend: Vue 3 + Vite + Element Plus app under `web/`.
|
||||
- Managed child services: Python projects under `managed/people_flow_project/` and `managed/store_dwell_alert/`.
|
||||
- Deployment assets: `deploy/`, root `Dockerfile`, `managed_services.yaml`.
|
||||
- Primary default ports from the current README: backend `9080`, frontend `13000`, child service APIs `18081` and `18082`.
|
||||
- Operating environment: this repository is intended for use in mainland China, so future changes must account for China-network constraints and domestic deployment realities.
|
||||
|
||||
## Repository Map
|
||||
|
||||
- `cmd/managed-portal/`: Go backend entrypoint.
|
||||
- `internal/config/`: backend configuration loading.
|
||||
- `internal/managed/`: managed service registry, runtime, remote client, orchestration logic.
|
||||
- `internal/server/`: HTTP server and handlers.
|
||||
- `internal/webdevice/`: web device proxying, rewriting, and related service logic.
|
||||
- `web/src/`: frontend app, router, API client, and views.
|
||||
- `managed/people_flow_project/`: Python people-flow service with `src/`, `tests/`, deployment scripts, and weights.
|
||||
- `managed/store_dwell_alert/`: Python store-dwell-alert service with `app/`, `tests/`, deployment scripts, and weights.
|
||||
- `deploy/`: Docker Compose deployment files and env files.
|
||||
- `docs/`: rollout and integration documentation.
|
||||
- `tasks/`: task plan, review evidence, and lessons learned.
|
||||
|
||||
## Workflow Orchestration
|
||||
|
||||
### 1) Plan Node Default
|
||||
|
||||
- For any non-trivial task, enter plan mode before implementation.
|
||||
- Treat a task as non-trivial if any of the following is true:
|
||||
- it needs 3 or more steps;
|
||||
- it involves architecture, sequencing, or cross-file decisions;
|
||||
- it requires a verification chain, not just a code edit.
|
||||
- Write the specification, scope, risks, and validation approach before making substantive changes.
|
||||
- If execution drifts, gets blocked, or a core assumption fails, stop and re-plan instead of forcing the current path.
|
||||
- Validation steps are part of the plan and are never optional.
|
||||
|
||||
### 2) Subagent Strategy
|
||||
|
||||
- Prefer subagents for exploration, repository search, investigation, and parallel analysis.
|
||||
- Keep one subagent focused on one clear tactical question.
|
||||
- For complex tasks, split exploration into parallel subproblems to protect the main context window.
|
||||
- Keep the main agent focused on decisions, edits, and verification.
|
||||
|
||||
### 3) Self-Improvement Loop
|
||||
|
||||
- At the start of a non-trivial task, quickly review `tasks/lessons.md` for rules relevant to the current work.
|
||||
- Any user correction must update `tasks/lessons.md`.
|
||||
- Record corrections in `trigger -> rule -> preventive action` form.
|
||||
- Use recorded lessons to prevent repeating the same process or decision error.
|
||||
|
||||
### 4) Verification Before Done
|
||||
|
||||
- Do not mark work complete without verification evidence.
|
||||
- When applicable, compare before and after behavior, not just changed files.
|
||||
- Run the narrowest meaningful validation first, then widen only if needed.
|
||||
- Report executable evidence such as tests, builds, lint, config checks, or log output.
|
||||
- Ask whether the result meets a staff-engineer standard before closing the task.
|
||||
|
||||
### 5) Demand Elegance (Balanced)
|
||||
|
||||
- Before a non-trivial change, ask whether a simpler, more robust design is available.
|
||||
- Replace obviously hacky solutions with the best reasonable implementation supported by current information.
|
||||
- Do not over-design straightforward fixes.
|
||||
|
||||
### 6) Autonomous Bug Fixing
|
||||
|
||||
- Treat bug reports as requests to diagnose and fix, not as prompts for the user to drive every step.
|
||||
- Use logs, failing behavior, and targeted tests to find the root cause.
|
||||
- Close the loop with a fix plus validation inside task scope.
|
||||
- When CI-like failures are in scope, investigate and repair them autonomously.
|
||||
|
||||
## Task Management
|
||||
|
||||
### 1) Plan First
|
||||
|
||||
- Before substantive implementation on a non-trivial task, create or update `tasks/todo.md`.
|
||||
- The plan must use checkboxes and include scope, risks, and validation intent.
|
||||
|
||||
### 2) Verify Plan
|
||||
|
||||
- Confirm the plan covers the user request, repository-specific risks, and the expected verification path before coding.
|
||||
|
||||
### 3) Track Progress
|
||||
|
||||
- Update `tasks/todo.md` as tasks are completed.
|
||||
- Keep plan state accurate enough that another engineer could resume from it.
|
||||
|
||||
### 4) Explain Changes
|
||||
|
||||
- For each major step, provide a high-level explanation of what changed and why.
|
||||
|
||||
### 5) Document Results
|
||||
|
||||
- `tasks/todo.md` must contain a `Review` section with result and verification evidence.
|
||||
|
||||
### 6) Capture Lessons
|
||||
|
||||
- If the user corrected the process, assumptions, or implementation direction, update `tasks/lessons.md` before closing the task.
|
||||
|
||||
## Core Principles
|
||||
|
||||
- Simplicity First: prefer the smallest change that fully solves the problem.
|
||||
- No Laziness: find the real cause and avoid cosmetic patches.
|
||||
- Minimal Impact: limit edits to the necessary surface and reduce regression risk.
|
||||
|
||||
## China Mainland Environment Constraints
|
||||
|
||||
- Assume the software will run in mainland China networks by default.
|
||||
- Prefer China-accessible defaults for package mirrors, container registries, and third-party endpoints when code or documentation needs a default choice.
|
||||
- Do not hard-code dependencies on services that are commonly inaccessible or unstable from mainland China unless there is an explicit fallback or configurability.
|
||||
- When adding build, install, or deployment steps, consider whether Go, Node, Python, Docker, and model-download paths need domestic mirror support.
|
||||
- When integrating external APIs, downloads, or web assets, make network reachability, timeout behavior, and fallback strategy explicit.
|
||||
- Keep region-specific choices configurable so the repo can still run elsewhere, but mainland China should be the default assumption.
|
||||
|
||||
## Repo-Specific Change Rules
|
||||
|
||||
### Backend Go Rules
|
||||
|
||||
- Backend entry code belongs in `cmd/managed-portal/`; business logic belongs in `internal/`.
|
||||
- Keep configuration behavior coherent across `internal/config/`, `deploy/`, and the README when ports, env vars, or service addresses change.
|
||||
- When editing service management logic, check adjacent tests in `internal/managed/`, `internal/server/`, and `internal/webdevice/`.
|
||||
- Prefer focused package tests before full-repo Go tests.
|
||||
|
||||
### Frontend Rules
|
||||
|
||||
- Frontend changes belong under `web/src/` and should respect the current Vite + Vue 3 structure.
|
||||
- When changing routes, views, or API calls, verify the corresponding backend endpoints or proxy paths still match.
|
||||
- Prefer minimal UI changes consistent with the existing portal instead of introducing a new design language.
|
||||
|
||||
### Managed Python Service Rules
|
||||
|
||||
- Treat `managed/people_flow_project/` and `managed/store_dwell_alert/` as embedded but separately testable projects.
|
||||
- Keep edits contained to the relevant child service unless a shared contract change requires broader updates.
|
||||
- Preserve deployment/runtime assumptions in each child project's scripts, configs, and tests.
|
||||
- Be careful with large model weights and local config files; do not assume ignored assets exist in source control.
|
||||
|
||||
### Deployment And Operations Rules
|
||||
|
||||
- For changes touching `deploy/docker-compose.yml`, env files, root `Dockerfile`, or child-service Docker assets, verify configuration consistency.
|
||||
- For registry or service-address changes, keep `managed_services.yaml`, deployment files, and README examples aligned.
|
||||
- Do not bulk-sync from external directories into this repo without a diff plan, overwrite-risk check, and rollback path.
|
||||
- For dependency installation, image builds, or artifact downloads, prefer defaults that are reliable from mainland China or document the required mirror configuration.
|
||||
|
||||
## Validation Matrix
|
||||
|
||||
- Go backend changes:
|
||||
- Prefer targeted `go test` commands for touched packages.
|
||||
- Use `go test ./...` when the change spans multiple backend packages or contracts.
|
||||
- Frontend changes:
|
||||
- Prefer `pnpm build` in `web/` for structural verification.
|
||||
- Use narrower checks when available, but do not skip build validation for meaningful UI or routing changes.
|
||||
- Python child service changes:
|
||||
- Prefer targeted test files under each project's `tests/` directory.
|
||||
- Expand to broader test runs only when the change crosses module boundaries.
|
||||
- Deployment/configuration changes:
|
||||
- Validate with the narrowest config check available, such as compose config rendering or related test coverage.
|
||||
- Documentation-only changes:
|
||||
- Verify file presence, required sections, and consistency with the current repository structure.
|
||||
|
||||
## Required Artifacts For Non-Trivial Tasks
|
||||
|
||||
- `tasks/todo.md`: current checklist, scope, risks, and review evidence.
|
||||
- `tasks/lessons.md`: updated whenever the user corrects the workflow or technical direction.
|
||||
- Final response: concise summary, what was verified, and any residual risk or natural next step.
|
||||
|
||||
## Definition Of Done
|
||||
|
||||
Do not close a non-trivial task until all of the following are true:
|
||||
|
||||
1. The request is fully covered.
|
||||
2. Plan items in `tasks/todo.md` are updated.
|
||||
3. Key verification has run and is reproducible.
|
||||
4. `tasks/todo.md` includes a completed `Review` section.
|
||||
5. `tasks/lessons.md` was updated for any user correction in the task.
|
||||
Reference in New Issue
Block a user