649 lines
12 KiB
Markdown
649 lines
12 KiB
Markdown
# AGENT.md
|
|
|
|
# Azurian Software Factory - AI Engineering Rules
|
|
|
|
This file defines mandatory rules for AI coding agents working on the Azurian Software Factory repository.
|
|
|
|
Read this document before modifying code.
|
|
|
|
---
|
|
|
|
## 1. Product Identity
|
|
|
|
Product:
|
|
|
|
**Azurian Software Factory (ASF)**
|
|
|
|
Tagline:
|
|
|
|
> From Requirement to Production, everything is contextualized, traceable and AI-accessible.
|
|
|
|
ASF is an AI-native, multi-tenant Software Factory SaaS.
|
|
|
|
ASF connects the complete software lifecycle:
|
|
|
|
Requirement → Architecture → Task → Code → Commit → Pull Request → Build → Test → Deployment → Runtime → Incident → Feedback.
|
|
|
|
ASF is not merely an AI coding assistant.
|
|
|
|
---
|
|
|
|
## 2. Core Principle
|
|
|
|
The central ASF principle is:
|
|
|
|
> Everything is an Artifact.
|
|
|
|
Requirements, architecture decisions, documents, source code references, commits, tests, builds, deployments, incidents and AI analyses can all be represented as Artifacts.
|
|
|
|
Artifacts may have relationships with other Artifacts.
|
|
|
|
Never implement functionality that unnecessarily breaks this generic model.
|
|
|
|
---
|
|
|
|
## 3. Architectural Principles
|
|
|
|
All implementations must preserve:
|
|
|
|
1. Multi-tenancy
|
|
2. Traceability
|
|
3. Context preservation
|
|
4. API-first design
|
|
5. Event-driven architecture
|
|
6. AI provider independence
|
|
7. Integration provider independence
|
|
8. Horizontal scalability
|
|
9. Auditability
|
|
10. Security by design
|
|
|
|
---
|
|
|
|
## 4. Technology Baseline
|
|
|
|
### Backend
|
|
|
|
Use:
|
|
|
|
- Python 3.12+
|
|
- FastAPI
|
|
- Pydantic
|
|
- async/await
|
|
- MongoDB
|
|
- RabbitMQ
|
|
- Redis
|
|
- MinIO/S3
|
|
|
|
Do not introduce another primary database without an ADR.
|
|
|
|
### Frontend
|
|
|
|
Use:
|
|
|
|
- Next.js
|
|
- React
|
|
- TypeScript
|
|
- Tailwind CSS
|
|
- shadcn/ui
|
|
- TanStack Query
|
|
- React Flow
|
|
|
|
Use Zustand only where persistent/shared client state is genuinely necessary.
|
|
|
|
### AI
|
|
|
|
All model access must go through the ASF AI Gateway abstraction.
|
|
|
|
Never call a specific LLM provider directly from domain/business code.
|
|
|
|
### Messaging
|
|
|
|
RabbitMQ is the primary event and asynchronous messaging backbone.
|
|
|
|
MongoDB is the persistent source of truth for job state.
|
|
|
|
---
|
|
|
|
## 5. Multi-Tenancy
|
|
|
|
Every tenant-owned entity must contain `tenant_id`.
|
|
|
|
Where appropriate it must also contain `project_id`.
|
|
|
|
Never trust tenant identity supplied directly by a browser request.
|
|
|
|
Tenant context must come from validated authentication/authorization context.
|
|
|
|
Every database query involving tenant-owned data must be tenant scoped.
|
|
|
|
Cross-tenant data leakage is considered a critical defect.
|
|
|
|
Tests must cover tenant isolation for sensitive operations.
|
|
|
|
---
|
|
|
|
## 6. Artifact Rules
|
|
|
|
Prefer the generic Artifact model for lifecycle entities.
|
|
|
|
Artifact types may include:
|
|
|
|
- requirement
|
|
- epic
|
|
- story
|
|
- task
|
|
- architecture_decision
|
|
- document
|
|
- source_file
|
|
- commit
|
|
- pull_request
|
|
- build
|
|
- test
|
|
- deployment
|
|
- release
|
|
- security_finding
|
|
- runtime_event
|
|
- incident
|
|
- ai_analysis
|
|
|
|
Do not create a new MongoDB collection for every artifact type unless there is a documented architectural reason.
|
|
|
|
Artifact metadata must remain extensible.
|
|
|
|
---
|
|
|
|
## 7. Relationships
|
|
|
|
Artifact relationships must be explicit and queryable.
|
|
|
|
Examples:
|
|
|
|
- implements
|
|
- implemented_by
|
|
- verifies
|
|
- verified_by
|
|
- generated_from
|
|
- documented_by
|
|
- depends_on
|
|
- affects
|
|
- deployed_as
|
|
- caused_by
|
|
- supersedes
|
|
- related_to
|
|
|
|
Do not encode important traceability relationships only inside free text.
|
|
|
|
---
|
|
|
|
## 8. Context
|
|
|
|
AI operations must receive relevant context through the ASF Context Engine.
|
|
|
|
Do not build arbitrary RAG logic directly inside API endpoints or UI code.
|
|
|
|
Context retrieval must remain independently evolvable.
|
|
|
|
The architecture must allow future integration of:
|
|
|
|
- embeddings
|
|
- vector search
|
|
- graph traversal
|
|
- source code indexing
|
|
- document indexing
|
|
- runtime telemetry
|
|
|
|
---
|
|
|
|
## 9. AI Rules
|
|
|
|
ASF must remain model agnostic.
|
|
|
|
Supported architectures may include:
|
|
|
|
- DGX-hosted models
|
|
- OpenAI-compatible APIs
|
|
- external providers
|
|
- future customer-hosted models
|
|
|
|
Model selection belongs to the AI Gateway.
|
|
|
|
Business services request capabilities, not specific model implementations.
|
|
|
|
Prefer concepts such as:
|
|
|
|
`analyze_code()`
|
|
|
|
over:
|
|
|
|
`call_qwen()`
|
|
|
|
unless inside a provider adapter.
|
|
|
|
Record AI usage when technically available.
|
|
|
|
Never expose model credentials to frontend code.
|
|
|
|
---
|
|
|
|
## 10. Queue Rules
|
|
|
|
Separate interactive and background workloads.
|
|
|
|
Typical queues:
|
|
|
|
- asf.ai.interactive
|
|
- asf.ai.background
|
|
- asf.indexing
|
|
- asf.code_analysis
|
|
- asf.testing
|
|
- asf.devops
|
|
- asf.notifications
|
|
|
|
Interactive user requests should receive higher scheduling priority than non-critical background work.
|
|
|
|
Workers must be stateless where practical and horizontally scalable.
|
|
|
|
Do not rely on process memory for persistent job state.
|
|
|
|
Consumers must be designed for duplicate delivery.
|
|
|
|
Where side effects occur, use idempotency mechanisms.
|
|
|
|
Do not assume exactly-once delivery.
|
|
|
|
---
|
|
|
|
## 11. Event Rules
|
|
|
|
Events describe facts that happened.
|
|
|
|
Prefer:
|
|
|
|
`artifact.created`
|
|
|
|
`requirement.updated`
|
|
|
|
`deployment.completed`
|
|
|
|
instead of ambiguous event names.
|
|
|
|
Every distributed event should contain sufficient metadata for tracing, including where applicable:
|
|
|
|
- event_id
|
|
- event_type
|
|
- timestamp
|
|
- tenant_id
|
|
- project_id
|
|
- correlation_id
|
|
- causation_id
|
|
- payload
|
|
|
|
Do not place large binary content directly in RabbitMQ messages.
|
|
|
|
Store large content in MinIO and transmit a reference.
|
|
|
|
---
|
|
|
|
## 12. MinIO Rules
|
|
|
|
Use MinIO/S3 for:
|
|
|
|
- uploaded documents
|
|
- generated files
|
|
- large reports
|
|
- repository archives where appropriate
|
|
- large AI inputs/outputs where persistence is required
|
|
|
|
MongoDB should store metadata and object references.
|
|
|
|
Do not store large binary objects directly in normal MongoDB documents unless specifically justified.
|
|
|
|
---
|
|
|
|
## 13. API Rules
|
|
|
|
REST API prefix:
|
|
|
|
`/api/v1`
|
|
|
|
Health endpoint:
|
|
|
|
`GET /api/v1/health`
|
|
|
|
Use:
|
|
|
|
- Pydantic request/response models
|
|
- explicit validation
|
|
- consistent HTTP status codes
|
|
- consistent error responses
|
|
|
|
Do not expose MongoDB internal structures directly through APIs.
|
|
|
|
Do not put business logic directly inside FastAPI route functions.
|
|
|
|
Routes should delegate to application/domain services.
|
|
|
|
---
|
|
|
|
## 14. Python Rules
|
|
|
|
Use type hints.
|
|
|
|
Prefer async I/O for:
|
|
|
|
- MongoDB
|
|
- RabbitMQ
|
|
- Redis
|
|
- HTTP
|
|
- MinIO operations where supported
|
|
|
|
Keep functions focused.
|
|
|
|
Avoid giant service classes.
|
|
|
|
Avoid hidden global state.
|
|
|
|
Use dependency injection where it improves testing and separation.
|
|
|
|
Do not catch `Exception` unless there is a deliberate boundary-level reason.
|
|
|
|
Never silently ignore errors.
|
|
|
|
---
|
|
|
|
## 15. Frontend Rules
|
|
|
|
Frontend components must not contain backend business rules.
|
|
|
|
Never access MongoDB, RabbitMQ, Redis or MinIO directly from the browser.
|
|
|
|
Use the ASF API.
|
|
|
|
Pages must support:
|
|
|
|
- loading state
|
|
- empty state
|
|
- error state
|
|
|
|
Do not present mocked data as production data.
|
|
|
|
Traceability visualization must use reusable node/edge components.
|
|
|
|
The UI must remain responsive and accessible.
|
|
|
|
---
|
|
|
|
## 16. Security Rules
|
|
|
|
Never commit:
|
|
|
|
- passwords
|
|
- API keys
|
|
- private keys
|
|
- tokens
|
|
- certificates
|
|
- production credentials
|
|
|
|
Use environment configuration.
|
|
|
|
Provide `.env.example` containing names and safe placeholder values only.
|
|
|
|
Never log authentication secrets.
|
|
|
|
Validate uploaded files.
|
|
|
|
Validate external connector input.
|
|
|
|
Assume external webhook payloads are untrusted.
|
|
|
|
---
|
|
|
|
## 17. Logging and Observability
|
|
|
|
Use structured JSON logging on backend services.
|
|
|
|
Propagate where applicable:
|
|
|
|
- correlation_id
|
|
- tenant_id
|
|
- project_id
|
|
- job_id
|
|
|
|
Prepare services for OpenTelemetry instrumentation.
|
|
|
|
Logs are operational telemetry.
|
|
|
|
Audit events are business/security records.
|
|
|
|
Do not confuse the two concepts.
|
|
|
|
---
|
|
|
|
## 18. Connectors
|
|
|
|
External systems must be isolated behind connector interfaces.
|
|
|
|
Examples:
|
|
|
|
- GitHub
|
|
- GitLab
|
|
- Bitbucket
|
|
- Jira
|
|
- Confluence
|
|
- Notion
|
|
- Jenkins
|
|
- SonarQube
|
|
- Grafana
|
|
|
|
Do not spread provider-specific APIs throughout ASF business code.
|
|
|
|
MCP should be preferred where it provides a suitable standardized capability.
|
|
|
|
REST and Webhooks remain supported integration mechanisms.
|
|
|
|
---
|
|
|
|
## 19. Testing Rules
|
|
|
|
Backend tests use pytest.
|
|
|
|
Tests should cover:
|
|
|
|
- domain logic
|
|
- API behavior
|
|
- artifact relationships
|
|
- job state transitions
|
|
- event handling
|
|
- tenant isolation
|
|
|
|
Bug fixes should include regression tests where practical.
|
|
|
|
Do not remove failing tests merely to make the build green.
|
|
|
|
---
|
|
|
|
## 20. Database Rules
|
|
|
|
MongoDB is the primary ASF datastore.
|
|
|
|
Collections and indexes must be intentionally designed.
|
|
|
|
Common queries must have appropriate indexes.
|
|
|
|
Tenant-aware compound indexes should be considered.
|
|
|
|
Schema flexibility does not mean schema absence.
|
|
|
|
Pydantic models define application-level contracts.
|
|
|
|
Database migrations or data transformation scripts must be versioned.
|
|
|
|
---
|
|
|
|
## 21. Architectural Decisions
|
|
|
|
Significant architectural decisions require an ADR under:
|
|
|
|
`docs/adr/`
|
|
|
|
Examples:
|
|
|
|
- introducing a new database
|
|
- introducing a new message broker
|
|
- changing tenancy strategy
|
|
- changing authentication architecture
|
|
- introducing a graph database
|
|
- changing artifact representation
|
|
- replacing the AI Gateway
|
|
- changing event semantics
|
|
|
|
Do not make major architectural changes silently.
|
|
|
|
---
|
|
|
|
## 22. Code Changes
|
|
|
|
Before modifying code:
|
|
|
|
1. Understand the requested change.
|
|
2. Inspect relevant existing code.
|
|
3. Identify affected modules.
|
|
4. Check existing tests.
|
|
5. Preserve architectural boundaries.
|
|
|
|
After modifying code:
|
|
|
|
1. Run relevant tests.
|
|
2. Run lint/type checks where configured.
|
|
3. Fix failures introduced by the change.
|
|
4. Review tenant isolation.
|
|
5. Review error handling.
|
|
6. Update documentation when behavior or architecture changed.
|
|
|
|
---
|
|
|
|
## 23. Dependency Policy
|
|
|
|
Do not add dependencies unnecessarily.
|
|
|
|
Before introducing a library, determine whether:
|
|
|
|
- the standard library already solves the problem
|
|
- an existing project dependency solves it
|
|
- the new dependency is actively maintained
|
|
- it introduces security or licensing concerns
|
|
|
|
Major framework additions require justification.
|
|
|
|
---
|
|
|
|
## 24. Simplicity
|
|
|
|
Do not over-engineer ASF.
|
|
|
|
Prefer:
|
|
|
|
simple → testable → observable → scalable
|
|
|
|
over:
|
|
|
|
complex → theoretical → difficult to operate.
|
|
|
|
Microservices are not a goal.
|
|
|
|
Service boundaries must exist because they provide operational or domain value.
|
|
|
|
---
|
|
|
|
## 25. Current Logical Components
|
|
|
|
The initial architecture consists of:
|
|
|
|
`asf-core`
|
|
|
|
Core API, organizations, projects, artifacts, relationships, jobs and audit.
|
|
|
|
`asf-context`
|
|
|
|
Context assembly, relationship traversal and future semantic retrieval.
|
|
|
|
`asf-ai`
|
|
|
|
AI Gateway, provider abstraction, routing and usage.
|
|
|
|
`asf-worker`
|
|
|
|
RabbitMQ consumers and asynchronous processing.
|
|
|
|
`asf-web`
|
|
|
|
Next.js SaaS frontend.
|
|
|
|
Do not create additional services unless there is a clear reason.
|
|
|
|
---
|
|
|
|
## 26. Source of Truth
|
|
|
|
MongoDB:
|
|
structured application/domain state.
|
|
|
|
MinIO:
|
|
large files and binary artifacts.
|
|
|
|
RabbitMQ:
|
|
events and work delivery.
|
|
|
|
Redis:
|
|
temporary/cache/coordination state.
|
|
|
|
AI models:
|
|
never considered authoritative sources of ASF business data.
|
|
|
|
---
|
|
|
|
## 27. AI Generated Changes
|
|
|
|
AI-generated code is subject to exactly the same engineering standards as human-written code.
|
|
|
|
Never assume generated code is correct.
|
|
|
|
Validate:
|
|
|
|
- imports
|
|
- APIs
|
|
- library versions
|
|
- async behavior
|
|
- security
|
|
- tenancy
|
|
- error handling
|
|
- tests
|
|
|
|
Never invent an API from an external dependency when its actual interface can be inspected.
|
|
|
|
---
|
|
|
|
## 28. Definition of Done
|
|
|
|
A change is not complete merely because code was generated.
|
|
|
|
A change is complete when:
|
|
|
|
- implementation works
|
|
- relevant tests pass
|
|
- tenant isolation is preserved
|
|
- errors are handled
|
|
- observability is maintained
|
|
- architecture rules are respected
|
|
- documentation is updated where necessary
|
|
- no credentials or sensitive data were introduced
|
|
|
|
---
|
|
|
|
## 29. Guiding Question
|
|
|
|
When implementing any ASF feature, ask:
|
|
|
|
> Does this improve the connection between software context, traceability, automation and AI?
|
|
|
|
If the feature bypasses those principles, reconsider the implementation. |