refine agent guidance and project split

AGENTS.md

@@ -0,0 +1,154 @@
+# AGENTS.md
+
+This file guides agentic coding assistants operating in this repository.
+Current workspace: `C:\Users\A200477427\Learnings\AIOps-Docs`.
+
+## 1) Repository Overview
+- Repository type: docs-first (no in-repo application runtime yet).
+- Main artifacts: architecture/proposal markdown documents and diagrams.
+- Key markdown docs:
+  - `README.md`
+  - `AIOps_Product_Architecture_and_Commercialization.md`
+  - `AIOps_Architecture_Diagram_Explanation.md`
+  - `AIOps_Project_Proposal.md`
+- Key binary assets:
+  - `AIOps_Practical_Route_Architecture.png`
+  - `Implementable_AIOps_Platform_Route_A_Architecture.png`
+  - `AIOps_智能运维平台项目立项书.pdf`
+
+## 2) Rule Sources and Precedence
+Follow instructions in this order:
+1. System/developer/runtime instructions from the active harness.
+2. Repository Cursor/Copilot rules (if present).
+3. This `AGENTS.md` file.
+4. Existing repository patterns.
+
+Rule-file status checked in this repo:
+- `.cursorrules`: not found.
+- `.cursor/rules/`: not found.
+- `.github/copilot-instructions.md`: not found.
+
+Agent requirement:
+- Re-check the 3 rule locations before major edits.
+- If any are added later, treat them as higher priority than this file.
+
+## 3) Optimization Goals
+- Keep terminology consistent across all long-form docs.
+- Prefer focused, incremental edits over broad rewrites.
+- Keep markdown content and diagram references synchronized.
+- Avoid inventing tooling/process assumptions not present in repo.
+
+## 4) Build/Lint/Test Commands
+Important: this repository currently has no formal build system, linter config, or test suite.
+
+### 4.1 Current command reality
+- Build command: not applicable.
+- Lint command: not enforced by repository config.
+- Test command: not applicable.
+- Single-test command: not applicable (no tests exist yet).
+
+### 4.2 Optional local documentation checks
+Run only when Node.js is available in the environment.
+
+```bash
+# Lint all markdown files (optional)
+npx markdownlint-cli2 "**/*.md"
+
+# Lint one markdown file (single-file check)
+npx markdownlint-cli2 "README.md"
+```
+
+### 4.3 Future test templates (if tests are added)
+Update this section with actual project commands when a framework is introduced.
+
+```bash
+# Pytest: run all tests
+pytest
+
+# Pytest: run one test function
+pytest tests/test_example.py::test_specific_case
+```
+
+## 5) Documentation Style Guidelines
+
+### 5.1 Language and tone
+- Default language is Chinese with technical English terms preserved.
+- Keep writing professional, specific, and implementation oriented.
+- Prefer concrete statements over vague strategic wording.
+- Keep terms and definitions stable within each document.
+
+### 5.2 Structure and formatting
+- Use one top-level `#` heading per file.
+- Use clear heading hierarchy (`##`, `###`) with logical progression.
+- Keep numeric section prefixes when a document already uses them.
+- Use `---` only when it improves readability.
+
+### 5.3 Terminology consistency
+- Wrap module/service identifiers in backticks.
+- Keep canonical terms consistent across docs:
+  - `Incident`
+  - `RCA Result`
+  - `NormalizedEvent`
+  - `IncidentContext`
+  - `execution-gateway`
+  - `policy-engine`
+- Keep status flow wording consistent:
+  - `new -> triaged -> diagnosing -> remediating -> resolved/closed`
+
+### 5.4 Lists, tables, and links
+- Use bullets for principles, scope, constraints, and key points.
+- Use ordered lists for procedures and time-based sequences.
+- Use tables for role splits, capability matrices, and KPI definitions.
+- Keep table headers explicit and unambiguous.
+- Use relative links for local docs/images and verify exact filenames.
+
+## 6) Code Style Guidelines (for future code/scripts)
+This repo is docs-only today.
+If code/scripts are added, apply these defaults unless project configs override them.
+
+### 6.1 Imports
+- Do not use wildcard imports.
+- Group imports as: standard library, third-party, local modules.
+- Keep one import per line unless language idioms require grouping.
+- Remove unused imports in the same change.
+
+### 6.2 Formatting
+- Prefer automated formatters once configured.
+- Keep functions small and focused.
+- Avoid dead code and commented-out legacy blocks.
+
+### 6.3 Types and contracts
+- Add explicit types for public functions and interfaces.
+- Prefer narrow, precise types over broad untyped structures.
+- Validate external input at boundaries.
+- Keep schema/type names aligned with AIOps domain terminology.
+
+### 6.4 Naming
+- Use descriptive, domain-accurate names.
+- Avoid unclear abbreviations (except standard terms like RCA/KPI/SLA/MTTR).
+- Python naming: `snake_case` for functions/variables, `PascalCase` for classes.
+- TypeScript/JS naming: `camelCase` for functions/variables, `PascalCase` for types/classes.
+
+### 6.5 Error handling and logging
+- Fail fast on invalid state; do not silently swallow exceptions.
+- Return actionable errors with debugging context.
+- Separate user-facing errors from internal diagnostic details.
+- Prefer structured logs including incident id/service/action when available.
+- For automation actions, record actor, timestamp, and result.
+
+## 7) Change Management
+- Do not rename core docs unless explicitly requested.
+- Preserve historical rationale in proposal/architecture documents.
+- If canonical terms change in one doc, update related docs in the same change.
+- Keep diagram references and explanation text mutually consistent.
+- Prefer small, reviewable changes grouped by topic.
+
+## 8) Agent Completion Checklist
+Before finishing a task, verify:
+- Only necessary files changed.
+- Terminology is consistent with existing AIOps docs.
+- Local links and image references resolve.
+- Any optional checks you ran are reported with outcomes.
+- If no tests exist, state that explicitly.
+
+If repository structure or tooling changes, update this file in the same PR.