yangyl/managed-portal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: add AGENTS.md, tasks/todo.md, and tasks/lessons.md for workflow management

Browse Source
This commit is contained in:
skye.yue
2026-05-12 10:01:47 +08:00
parent ad3ce707f5
commit bc87fb78ea
3 changed files with 219 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
AGENTS.md Normal file
View 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.

15
tasks/lessons.md Normal file
View File

@@ -0,0 +1,15 @@
# Lessons
## 2026-05-12
- Trigger: the user corrected the execution workflow for non-trivial tasks and required persistent task tracking.
- Rule: for any non-trivial task, create or update `tasks/todo.md` before substantive implementation, keep progress current, and do not mark done without review evidence.
- Preventive action: check for `tasks/todo.md`, `tasks/lessons.md`, and repository guidance files before editing code; if the user corrects process expectations, record the rule immediately.
- Trigger: the user required corrections to be persisted for future sessions.
- Rule: any user correction must be recorded in `tasks/lessons.md` as `trigger -> rule -> preventive action`.
- Preventive action: after any correction, update lessons before closing the task and mention the recorded rule in the final verification summary.
- Trigger: the user clarified that this repository is meant to run in mainland China environments.
- Rule: future code, build, deployment, and integration changes must consider mainland China network accessibility and should prefer China-friendly defaults where practical.
- Preventive action: when adding dependencies, mirrors, external endpoints, or download flows, explicitly check whether the default path works reliably in mainland China and add configuration or fallback when needed.

25
tasks/todo.md Normal file
View File

@@ -0,0 +1,25 @@
# Task Plan
## Checklist
- [x] Clarify scope, repository boundaries, and validation requirements for a repository-level AGENTS.md.
- [x] Verify that the plan covers the user-specified workflow rules, project structure, and risk points.
- [x] Create a complete AGENTS.md that embeds the requested workflow orchestration rules and repo-specific guardrails.
- [x] Verify the generated AGENTS.md against the current repository structure and required workflow sections.
- [x] Update the Review section with the final result and verification evidence.
## Scope And Risks
- Scope: add a repository-root AGENTS.md that governs future modifications across the Go backend, Vue frontend, deployment assets, and embedded Python managed services.
- Risk: omit a repository area or validation command and leave future work under-constrained.
- Risk: copy the requested workflow rules without adapting them to this repo's actual layout and toolchain.
- Risk: finish without writing persistent task evidence for plan, review, and lessons.
## Review
- Status: completed.
- Result: added a repository-root `AGENTS.md` plus `tasks/todo.md` and `tasks/lessons.md` to enforce the requested workflow for future non-trivial tasks.
- Verification:
- confirmed `AGENTS.md` exists at the repository root;
- read back `AGENTS.md` and verified it covers workflow orchestration, task management, repo structure, validation matrix, and definition of done;
- matched required repository-specific references including `internal/webdevice/`, `managed/people_flow_project/`, `managed/store_dwell_alert/`, `tasks/todo.md`, and `tasks/lessons.md`.