first
This commit is contained in:
valenti
@@ -0,0 +1,649 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user