راهنمای پروژه

ساختار فایل‌های AI Agent یعنی چه؟

فایل‌های Markdown در یک پروژهٔ Agent فقط مستندات نیستند؛ هرکدام بخشی از رفتار، محدودیت‌ها یا روش انجام کار Agent را مشخص می‌کنند. این صفحه نقش هر فایل و نمونهٔ واقعی آن در همین پروژه را نشان می‌دهد.

اول ساختار را ببینیم

در این repository، دستورهای عمومی در ریشه قرار دارند و دستورهای تخصصی داخل پوشهٔ .agents نگهداری می‌شوند.

ai-agent-structure-guide/
├── AGENTS.md                         # قوانین عمومی پروژه
└── .agents/
    └── bmsd-clean-connector/        # توانایی تخصصی
        ├── SKILL.md                 # نقطهٔ ورود
        └── references/            # جزئیات تخصصی
            ├── rules.md
            ├── architecture.md
            ├── convention.md
            ├── reference.md
            └── security.md

نقش فایل‌ها

این‌ها مثال‌های واقعی هستند، نه فایل‌های فرضی.

AGENTS.md

قوانین سطح پروژه را مشخص می‌کند؛ مثلاً فناوری هدف، مرزهای مجاز تغییر و الزام build قبل از پایان کار.

قانون عمومی / Global rule
- Target .NET 8 only (`net8.0`).
- Preserve Clean Architecture dependency direction.
- Build affected projects before finishing.

.agents/.../SKILL.md

وقتی یک کار با یک توانایی تخصصی مرتبط است، نقطهٔ ورود Agent است و مشخص می‌کند چه referenceهایی و با چه ترتیبی خوانده شوند.

راهنمای انتخاب / Skill entry point
1. Inspect the solution.
2. Read references/rules.md.
3. Load only the needed reference.
4. Build the affected `net8.0` projects.

references/rules.md

قوانین الزام‌آور اجرا و quality gate را نگه می‌دارد؛ مثل استفاده از MediatR و جلوگیری از اضافه‌کردن dependency بدون اجازه.

قواعد اجرا / Implementation rules
- Use MediatR requests/handlers.
- Keep MediatR handlers thin.
- Do not introduce database storage structure.
- Do not log passwords, tokens, or secrets.

references/architecture.md

توضیح می‌دهد هر لایه چه مسئولیتی دارد و جریان ثبت سرویس‌ها، handlerها، logging و middleware چگونه باید باشد.

معماری / Architecture
Domain → Application → Infrastructure → Presentation

The handler remains orchestration-only.

references/convention.md

قراردادهای دقیق نام‌گذاری، route، مدل‌های request/response و روش ساخت مدل CRM را تعیین می‌کند.

قرارداد / Convention
Controller: ContactController
Command: UpdateContactStatusReasonByMobilePhoneCommand
Route: api/v1/Contact/UpdateStatusReasonByMobilePhone

references/reference.md

جزئیات مرجع فنی را نگه می‌دارد؛ مثل شکل CrmSettings، الگوی repository و نسخه‌های مجاز NuGet.

مرجع فنی / Technical reference
"Dataverse": {
  "Url": "",
  "Version": "9.1",
  "Authentication": "Windows"
}

این فایل‌ها چطور با هم کار می‌کنند؟

Agent ابتدا قوانین عمومی را می‌بیند، سپس اگر کار به یک حوزهٔ تخصصی مربوط باشد SKILL.md را به‌عنوان مسیر راهنما می‌خواند و فقط reference مرتبط را باز می‌کند.

۱. AGENTS.mdقوانین پروژه
۲. SKILL.mdمسیر تخصصی
۳. references/*.mdجزئیات لازم
۴. اجرا و بررسیتغییر + build

یک نکتهٔ مهم

اسم فایل‌ها قانون جهانی نیست. مهم این است که نقش هر فایل واضح باشد، قوانین عمومی از جزئیات تخصصی جدا بمانند و Agent بتواند از یک فایل راهنما به مرجع درست برسد. در این پروژه، نام واقعی فایل تخصصی SKILL.md است و قوانین آن در references/ تفکیک شده‌اند.