Практычныя прыказкі: Графы контексту для агентаў ШІ: як надаць ШІ памяць эксперта
Практычныя прыказкі: Графы контексту для агентаў ШІ: як надаць ШІ памяць эксперта: контракты, перакрычанні та шаблоны коду для команд, якія викорыстоўваюць гэты патэрн.
Чаму наступнам паколенню агентаў AI патрэбна больш за простае вектарнае пошук, эмбеддынгі і большыя вікна контэксту
Указаць тые часткі тексту, якія фактычна сталі падставай для адпаведнай адказы. Без цітатаў аператары не можуць разлічыць галюцинацію ад прасоў у індэксаванні.
Што такое граф контэксту?
EmployeeController.java exists.
ReimbursementService.java exists.
SecurityConfig.java exists.
ADR-17.md exists.
EmployeeController
|
| follows_pattern
v
EmployeeApiConvention
|
| requires
v
TenantValidation
ReimbursementEndpoint
|
| handled_by
v
ReimbursementOrchestrator
|
| writes_to
v
ReimbursementRepository
|
| persists
v
HrReimbursement
ReimbursementEndpoint
|
| governed_by
v
ADR-17
ADR-17
|
| created_because_of
v
ProductionIncident-928
Граф — гэта, па сутнасці, кропкі і лініі
У стадії «A Graph Is Basically» неабяжна праблема — перад тым, як зменшыць код, неабяжна задаць вхідныя даны, адпаведальнага за крок і критэрыі завершэння. Аперацыйныя працавнікі павінны магчымаць перзапуск кроку з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан. Неабяжна задокументаваць як шлях успеху, так і шлях вярнення да нормальнага стану. Перапрыбуткі, людзкія пераказы і обробка некоректных паведамленняў є часткай продукту, а не чымсь, што дадаецца пазней. Неабяжна прыкласты людзкія празгляды да тых елементаў, якіе витрачаюць грошы або зменяюць даны ў працэсе виробніцтва. Прыўязкі пад час компілявання не є гарантыяй полнай адпаведнасці продукту выклікам бізнесу. У стадії «A Graph Is Basically» неабяжна перад тым, як зменшыць код, задаць вхідныя даны, адпаведальнага за крок і критэрыі завершэння. Аперацыйныя працавнікі павінны магчымаць перзапуск кроку з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан. Спрыяйце цій стадіі як даговору межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Дайце назвы всім элементам, задаць критэрыі успеху і не прабоўваць прыймаць часткова завершаныя рэзультаты без падтверджэння.
Node ---- Relationship ---- Node
Vaibhav ---- works_at ---- PeopleStrong
Controller ---- calls ---- Service
Service ---- calls ---- Repository
Repository ---- writes_to ---- DatabaseTable
Endpoint ---- protected_by ---- Permission
Feature ---- explained_by ---- ADR
ADR ---- resulted_from ---- Incident
Test ---- validates ---- Endpoint
Граф знання протыка Граф контэксту
Калі працюеце над этапам Граф знання протыка Граф контэксту, спачатку запісайце умовы: неабяжлівыя даннэ, сігнал успеху і тое, што выходзіць у случае частковага нявыпання. Такі список контроля дапамагае заліцвачыць змяны коду. Запісуйце час выканання і кост токенаў або запытаў праза функцыйнае рэзультат. Відразлівасць костаў з самага пачатку запобегае неспакойным рахункам, калі праця пераходзіць з дэмаверсіі ў спакульнаныя сераўсы. Зробіце контрольную пунктую пасля дорогіх крокаў. Функцыя адновлення не должна зноў нарахоўваць косты за той самы вызов LLM, калі аператар прабуе зноў выконаць пазнейшы вузел.
Employee
WORKS_FOR
Organization
Order
BELONGS_TO
Customer
PaymentService
USES
PaymentRepository
PaymentService
USES
PaymentRepository
PaymentService
GOVERNED_BY
ADR-12ADR-12
CREATED_AFTER
Incident-492PaymentService
REQUIRES
FinancePermissionPaymentRepository
WRITES_TO
PaymentTransactionPaymentTransaction
MUST_BE_SCOPED_BY
OrganizationIDPaymentTransaction
MUST_BE_SCOPED_BY
TenantID
Найважнейшая частка: Графы контэксту храняць «чаму»
Калі працюеце над стадзіяй «Найважлівейшая частка», спачатку запісацеце кантракт: неабяжлівыя даны, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список пераконтроўвае чыстасць пазнейшых змян у кодзе. Храніце настройкі параду ўнутры коду прыемленае. Файлы сераўіса, хранальнікі секрэтных дадзеных і флагі функцый належаць у аднам месца, куды аператары можаць адбавляць пераказы без неабяжнага чытання всіх элементаў структуры. Стварайце контрольныя пункты пасля дорогіх крокаў. Система вярнення не павінна знову ставіць плату за той самы вызов LLM, калі аператар перапрыяўляе роботу да наступнага элемента.
Discount = 25%
Approved = true
ApprovedBy = 182
Customer-482
RECEIVED
25% Discount
25% Discount
APPROVED_BY
SalesDirector25% Discount
EXCEPTION_TO
StandardDiscountPolicyException
BECAUSE
CustomerMigrationRiskCustomerMigrationRisk
DOCUMENTED_IN
Opportunity-928Decision
PRODUCED
SuccessfulRenewal
Асновныя складовыя графа контэксту
Калі працуеце над асновнымі складовымі стадію, спачатку запісайце угоду: неабяжлівыя данні, сигнал працэздольнасці і тое, што выходзіць пад частковую нявыполненасць. Такі список пераканае ў тым, што пазнейшыя змены коду будуць чыстымі. Документавайце як шлях успеху, так і шлях вярнення. Перапрыбуткі, людзкі контроль і обработка некоректных паведамленняў є частью продукту, а не пазнейшым дапрацоўкам. Стварайце контрольныя пункты пасля дорогіх крокаў. Система вярнення не павінна знову ставіць плату за той самы вызов LLM, калі аператар перапрыбуе пазнейшы вузел. Калі працуеце над асновнымі складовымі стадію, спачатку запісайце угоду: неабяжлівыя данні, сигнал працэздольнасці і тое, што выходзіць пад частковую нявыполненасць. Такі список пераканае ў тым, што пазнейшыя змены коду будуць чыстымі. Спрыймайце гэтую стадію як угоду межа даннімі і перакананымі выходамі. Дайце назвы артыфактам, задаце правіла пераканання працэздольнасці і адмовіцеся ад тыхняе частковай завершэнні без паведамлення.
1. Энтытэты — тое, што існуе
Этап «1 Энтытэты, 1 Рэч» працюе найкраща, калі яго спрыяваць як мерыемую паверхню. Запісайце адна ідеальная транскрыпцыя, адзін прыклад неудачы і запіску пра вярнэнне да пачатковага стану, перш чым расширваць сферу дзеяння. Запісвайце часы выконання і кост токеноў або запытаў праза функцыйнае рэзультат. Відчутнасць костаў з самага пачатку запобегае неспакойным рахункам, калі процес пераходзіць з дэмавайнага режыма ў спяльныя среды. Храніце стан графа ў простам і типаваным формате. Вярнутыя структуры масавых дадзенняў закрываюць вачэнне на тое, який вузел запісаў канкрэтны поле, і спакшваюць продажчыку роботу пасля перарываў.
Repository
Module
Package
Class
Method
API Endpoint
Database Table
Database Column
Configuration
Skill
Rule
Architecture Decision
Pull Request
Commit
Issue
Incident
Test
Developer
Team
Node: ReimbursementController
Type: JavaClass
Path: services/hr/.../ReimbursementController.java
Node: POST /reimbursements
Type: Endpoint
Node: HrReimbursement
Type: DatabaseTable
2. Связі — як рэчы з’яўляюцца ў зв’язку
Два відношэння, якія дапамагаюць системе «Things stage» працаваць наяўна, калі яе спрыяваць як вимерную паверхню. Запісаўце адна «золатая» транскрыпцыю, адин прыклад неудачы і прыметку па вярнэнню да пачатковага стану пры расшырэнні масштаба. Зберагайце настройкі праза код аплікацыі. Файлы сераўіснага сэрвісу, хранілішчы секретных дадзеных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адбавляць контроль без неабяжнага чытання всіх дадзеных. Зберагайце стан графа ў простам і типаваным формате. Вкладныя блокі маскуюць інфармацыю пра тое, який вузел запісаў які поле, і спакшваюць продаж чытання дадзеных пасля перерываў.
ReimbursementController
EXPOSES
POST /reimbursements
POST /reimbursements
CALLS
ReimbursementService
ReimbursementService
USES
ReimbursementRepository
ReimbursementRepository
WRITES_TO
HrReimbursement
POST /reimbursements
REQUIRES_PERMISSION
CREATE_REIMBURSEMENT
ReimbursementService
FOLLOWS_PATTERN
OrchestratorPattern
3. Атрыбуты — дакладныя вінаваткі пра вузлы і відношэння
Тры ўласнасці, якія неабходны для апісання стадіі, найкраща выкарыстоўваць як мерыябельную паверхню. Зафіксуйце адны ідеальны прыклад роботы, адзін прыклад неудачы і прыметку па адвярненню змян перш чым расширваць масштабы. Документавайце як шлях успеху, так і шлях вяснавання ситуацыі. Перапрыбуткі, людзкі контроль і обработка некоректных паведамленняў є частью продукту, а не етапамі далейшай доўнелівання. Храніце стан графаў у простам і типаваным формате. Вкладзеныя структуры маскуюць інфармацыю пра тое, який вузел запісаў кожнае поле, і спакшуюць продовжэння роботы пасля перерываў. Тры ўласнасці, якія неабходны для апісання стадіі, найкраща выкарыстоўваць як мерыябельную паверхню. Зафіксуйце адны ідеальны прыклад роботы, адзін прыклад неудачы і прыметку па адвярненню змян перш чым расширваць масштабы. Расследзіце гэтую стадію як контракт межаў вхідных даных і перакананых выходных рэзультатаў. Дайце назвы артыфактам, задаць критэрыя успеху і не падтрымайце беззвучнае частковае завершэння роботы.
JavaClass:
name = ReimbursementController
language = Java
framework = Spring Boot
module = hr-service
Endpoint:
method = POST
path = /api/v1/reimbursements
authenticationRequired = true
Service
CALLS
Repository
since = 2026-04-18
confidence = 1.0
source = static-analysis
4. Час
Для стадіі 4 Time неабяжна прадзеўкаваць вхідныя даны, адпаведальнага за крок і крэтыяры завершэння пры перадзеўкванні коду. Аператары должны магчымае запускать крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Запісваць час выконання і кост токенаў або запытаў разам з функцыйнальнымі рэзултатамі. Відразы костаў з самага пачатку запобегае неспакойным рахункам, калі траекторыя пераходзіць з дэмавай версіі ў спяльныя среды. Заставіць людзкую апраўдку для тых крокаў, якія витрачаюць грошы або зменяюць даны ў працэсе. Кампіляцыйныя налашчэння не ўзроўнаўцуюцца з павнай адпаведнасцю бізнесу.
Controller
USES
FieldInjection
FieldInjectionPattern
validUntil = 2025-01-15
ConstructorInjectionPattern
validFrom = 2025-01-16
5. Паходжанне — звядзе гэтая інфармацыя?
Для етапа «5 Provenance Where Did» неабяжна пад час змены коду адзначыць вхідныя даны, власніка крока і критэрыі завершэння. Аперацыяныя працавнікі должны магчымае запускаць крок з вядомай точкі контролю, не падозрываючы схованы стан. Конфігурацыю трэба залічваць параду ад коду прыкладнення. Файлы сераўіса, хранільнікі секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, якое працавнікі можуць пераглядаць, не чытаючы весь ланцуг задач. Пры выконанні дзеянь, якія коштуюць грошы або зменяюць даны у працоўным режыме, неабяжна людская апраўда. Падключэння пад час компіляцыі не ўзроўнаўаеся з повнайасцю бізнес-процэсаў.
Rule:
All employee APIs must validate TenantID.
Rule
EXTRACTED_FROM
ADR-0027.md
Rule
OBSERVED_IN
14 Production Endpoints
Rule
INTRODUCED_BY
PR-8421
6. Короткатэрмінная памяць
Для стадіі 6 «Короткатрывалая память» неабяжна ўзначыць вхідныя даны, адпаведальнага за этап і крэтырыя завершэння пры перадзеі коду. Аперацыйныя працавнікі должны магчымае запускаць этап з вядомай точкі контролю без неабяжнага вычыслення захаванога стану. Неабяжна задокументаваць як шлях успеху, так і шлях вярнення да нормальнага стану. Перапрыбуткі, людзкія пераказы і обробка некоректных паведамленняў ёсцю часткай продукту, а не элементамі пазнейшага дапрацоўкі. Неабяжна прыняць людзкую затверджэнне для тых крокаў, якія выкарыстоўваюць грошы або зміняюць даны праўдзівай роботы. Компіляцыйныя налашчэння не ўзначаюць полной готовасці продукту для выкарыстоўвання. Для стадіі 6 «Короткатрывалая память» неабяжна ўзначыць вхідныя даны, адпаведальнага за этап і крэтырыя завершэння пры перадзеі коду. Аперацыйныя працавнікі должны магчымае запускаць этап з вядомай точкі контролю без неабяжнага вычыслення захаванога стану. Спрыяць гэтай стадіі як кантракту межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Даць назвы артыфактам, узначыць крэтырыя успеху і не дазволіць тылу частковага завершэння без паведамлення.
CurrentTask
TARGETS
AdminAPI
CurrentTask
EXCLUDES
EmployeeApp
7. Даўнэйшая памяць
Калі працуеце над 7-ю стадзіяй даўнэйшай памяці, спачатку запісуйце умовы кантракту: неабходныя даны, сігнал успеху і тое, што выканаецца у разы частковага невялікога браку. Такі чарт дапамагае заліцвачыць змяны ў кодзе паштоўна. Запісвайце час выканання і кост токеноў або запытаў па боку функцыйнаых рэзультатаў. Відразлівасць костаў з самага пачатку запобегае неспакойным рахункам, калі працэс пераходзіць з дэмовай среды ў спяльнаныя сераўеры. Зробіце перапаказ пасля дорогіх крокаў. Система вярнення працы не должна знову нараховваць косты за той самы вызыв LLM, калі аператар прабуе зноў выканаць пазнейшы вузел.
Repository
USES
Java17
Repository
USES
SpringBoot3EndpointCreation
REQUIRES
ControllerTestEndpointCreation
REQUIRES
ServiceTest
8. Памяць прыняцтва рашэнняў або разумовых процэсаў
Калі працюеце над 8 стадзяміямі рашэння або аналізу, спачатку запісайце контракт: неабяжлівыя даны, сігнал успеху і тое, што выходзіць у разе частковага неяксамоства. Такі список пераконтролюе чыстасць пазнейшых змян у кодзе. Зберагаюце настройкі за межамі коду прыемлена. Файлы сераўнавання, хранільнікі секрэтных дадзеных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адбавіць аудыт без неабяжлівага чытання всей структуры. Кэшавайце стабільныя інструкцыі системы і схемы інструментаў. Перадача ідэнтычных прамулкіў ёсць частым выказаннем затрачання ресурсаў.
Approach A:
Controller -> Repository
Business logic must pass through the service/orchestrator layer.
Approach-A
REJECTED_BECAUSE
ArchitectureRule-42
Як жа на самай працуе Контэкстны граф?
Калі працуеце над этапам «So How Does it work?», спачатку запісайце умовы кантракту: неабяжлівыя данні, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список пераконвае ў тым, што пазнейшыя змены коду будуць чыстымі. Документавайце як шлях успеху, так і шлях вярнення да нормы. Перапрыбуткі, людзкія контралі і обработка некоректных паведамленняў є частью продукту, а не пазнейшым дапрацоўкам. Стварайце контрольныя пункты пасля дорогіх крокаў. Система вярнення не должна зноў ставіць плату за той самы вызов LLM, калі аператар перапрыбуе пазнейшы вузел. Калі працуеце над этапам «So How Does it work?», спачатку запісайце умовы кантракту: неабяжлівыя данні, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список пераконвае ў тым, што пазнейшыя змены коду будуць чыстымі. Спрыймайце этап як кантракт межа даннімаў і перакананымі выходнымі рэзультатамі. Даўце назвы артыфактам, задайце критэрыя успеху і адмовіцеся ад тыхнейкага частковага завершэння.
Task:
Create Endpoint
Domain:
ReimbursementOperation:
ApproveActor:
Admin
Шаг 1 — Знайсці вузлы-пачатак
Першы шаг – выявленне стадій – найэфектыўней працюе, калі яго розглядаць як вимерную плошчу. Запісайте адна ідеальная транскрыпцыя, адзін прыклад неудачы і прыметку па адвярненню змян перш чым расширваць масштабы. Запісуйце часы виконання і косты токеноў або запытаў разам з функцыйнальнымі рэзультатамі. Візуабельнасць костаў з самага пачатку запобегае неспакою, калі процес пераходзіць з дэмаверсіі ў спяльныя сераўы. Храніце стан графа як плоскі і з адначыяным типам дадзеных. Вкладаныя блокі маскуюць інфармацыю пра тое, який вузел запісаў якое поле, і спакшваюць продажчыку роботу пасля перерываў.
Reimbursement
Approve
Endpoint
Admin
ReimbursementController
ReimbursementService
HrReimbursement
ReimbursementStatus
APPROVE_REIMBURSEMENT permission
ReimbursementWorkflow
Шаг 2 – Расширэнне ўзаімных зв’язкаў
Этап 2 «Расшырэнне ў сваім стадзія» працуе наўсёрэйш, калі яго расследжваць як вимерную паверхню. Перад расшырэнням масштаба зафіксавайце адны «золаты» транскрыпт, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану. Зберагайце настройкі пазырочна ад коду прыемліцеля. Файлы сяродавішча, хранільнікі секрэтных дадзеных і флагі функцыяў должны знаходзіцца ў аднам месцы, куды аператары можаць адбавляць контроль без неабяжнага чытання всіх дадзеных. Зберагайце стан графа ў простам і типаваным формате. Вярнутыя блокі маскуюць інфармацыю пра тое, який вузел запісаў якое поле, і спакойваюць працэс пасля перарываў.
ReimbursementController
|
+--- FOLLOWS_PATTERN ---> ExpenseController
|
+--- CALLS -------------> ReimbursementService
|
+--- PROTECTED_BY ------> FinancePermission
ReimbursementService
|
+--- USES --------------> ReimbursementOrchestrator
ReimbursementOrchestrator
|
+--- WRITES_TO ---------> HrReimbursement
|
+--- GOVERNED_BY -------> ADR-24
ADR-24
|
+--- CREATED_AFTER -----> Incident-842
Этап 3 — Фільтрацыя графа
Этап «Фільтрацыя, крок 3» працюе наўсёх лепш, калі яго спрыяваць як мерыемую паверхню. Зафіксавайце адна ідеальная транскрыпцыя, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць сферу дзеяння. Дакументавайце як шлях успеху, так і шлях вяснавання. Перапрыбуткі, людзкія контралі і обработка некоректных паведамленняў є часткай продукту, а не наступным этапам дорабачання. Храніце стан графа ў простам і типаваным формате. Вкладзеныя блокі маскуюць, який вузел запісаў канкрэтны поле, і спакоююць продовжэнне роботы пасля перарываў. Этап «Фільтрацыя, крок 3» працюе наўсёх лепш, калі яго спрыяваць як мерыемую паверхню. Зафіксавайце адна ідеальная транскрыпцыя, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць сферу дзеяння. Спрыявайце гэты этап як кантракт межа вхіднымі даннымі і перакананымі выходнымі рэзультатамі. Даўце назвы артыфактам, задайце критэрыя успеху і адмовіцеся ад мовчанкавага частковага завершэння.
current branch
current module
task
user permission
repository version
organization
time
confidence
Крок 4 — Стварэнне контексту агента
Для 4-го крока «Стварэнне сцэны» неабяжна прадзерагаваць вхідныя даны, адпаведальнага за крок і критэрыі завершэння пры перадзяле практыку. Аператары должны магчымаць перзапуск кроку з вядомай точкі контролю, не падозрываючы схованы стан. Запісваць трываласць выконання і кост токенаў або запытаў разам з функцыйнальнымі рэзултатамі. Відразы костаў з самага пачатку запобегае неспакойным рахункам, калі процес пераходзіць з дэмавайнага режыма ў спяльныя среды. Неабяжна атрымаць пашчаткованне чалавека для тых крокоў, якія витрачаюць грошы або зменяюць даны ў працэсе виробніцтва. Праця ў часе компілявання не абавесць цэлыснасцю бізнес-процэса.
TASK
Create reimbursement approval endpoint.
RELEVANT PATTERN
ExpenseApprovalController.REQUIRED ARCHITECTURE
Controller -> Service -> Orchestrator -> Repository.SECURITY
Permission APPROVE_REIMBURSEMENT required.TENANCY
Queries must include OrganizationID and TenantID.DATABASE
HrReimbursement.IMPORTANT DECISION
ADR-24 prohibits direct status updates.TEST PATTERN
ExpenseApprovalControllerTest.
5-й крок — Агент выканае работу
Для этапу «Агент выканана дзеянне 5» неабходна прадзеўжэнне: перад змянай коду трэба адзначыць вхідныя даны, адпаведальнага за этап і крэтарыя для завершэння. Аператары должны магчымае запускваць этап з вядомай точкі контролю, не падозрываючы прыхованы стан. Конфігурацыю трэба заставіць празае ўнутрошняй часткай коду прыемлівання. Файлы сяродавішча, хранільнікі секрэтных дадзеных і флагі функцияў должны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць, не чытаяўшы весь ланцуг. Прыявка ад чалавека неабходна для рэласаў, якія витрачаюць грошы або зменяюць даны ў працэсе. Прыўязка на час компілявання не є падтверджэннем полнайасці бізнес-процэса.
Controller
Request DTO
Response DTO
Service
Orchestrator
Repository query
Authorization
Tenant filtering
Tests
Этап 6 — Зберагчы тое, што адбылася
Для стадіі «Step 6 Store What» неабяжна ўзначыць вхідныя даны, адпаведальнага за выкананне крока і крэтыяры завершэння пры зміне коду. Аперацыйныя працавнікі должны магчымае перадзеяць крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Неабяжна задокументаваць як шлях успеху, так і шлях вярнення да нормальнага стану. Перапрыбуткі, людзкія пераказы і обробка некоректных паведамленняў є часткай продукту, а не дадатковымі элементамі пасля його стварэння. Неабяжна застаўіць людзкую апраўдку для тых крокаў, якія выкарыстоўваюць грошы або зміняюць даны ў працэсе виробніцтва. Конфігурацыя ў часе компілявання не є гарантыяй полнай адпаведнасці продукту бізнес-трэбованням. Для стадіі «Step 6 Store What» неабяжна ўзначыць вхідныя даны, адпаведальнага за выкананне крока і крэтыяры завершэння пры зміне коду. Аперацыйныя працавнікі должны магчымае перадзеяць крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Спрыяць гэтай стадіі як кантракту межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Даць назвы всім элементам, узначыць крэтыяры успеху і не прабаваць прыймаць часткова завершаныя рэзультаты без падтверджэння.
PR-9928
IMPLEMENTED
ReimbursementApprovalEndpoint
ReimbursementApprovalEndpoint
FOLLOWS
OrchestratorPattern
PR-9928
VALIDATED_BY
ArchitectureTests
База дадзеных вектараў протык Context Graph
Кал працуеце над аспектамі Базы дадзеных вектараў протык Context Graph, спачатку запісайце умовы викорыстоўвання: неабходныя данні, сігнал успеху і тое, што выканаецца у разе частковага нявыпання задачы. Такі список дапамагае заліцваліваць будучыя змены ў кодзе. Запісвайце час выконання і кост токеноў або запытаў разам з функцыйнальнымі рэзультатамі. Відразлівая ведамасць пра косцы з’яўляецца неспакойныя рахункі, калі працэс пераходзіць з дамовай версіі ў спакульнаныя сераўеры. Зробіце контрольную пунктую пасля дорогіх крокаў. Функцыя адновлення не должна зноў нараховваць косты за той самы вызыв LLM, калі аператар прабуе зноў выканаць пазнейшы элемент.
EmployeeController.java
EmployeeService.java
EmployeeRepository.java
SecurityConfig.java
ADR-17.md
Incident-928.md
EmployeeControllerTest.java
add-end-point/SKILL.md
Што робіць вектарны пошук
Калі працюеце над этапам «Што такое векторный поиск», спачатку запісайце шаблон: неабяжлівыя даны, сигнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список контроля дапамагае заліцвачыць змяны ў кодзе пазнейша. Зберагайце настройкі за межамі коду прыемліка. Файлы сераўнавання, хранільнікі секрэтных данных і флагі функций павінны знаходзіцца ў адном месцы, куды аператары можаюць аудытаваць іх, не чытаючы весь граф. Стварайце контрольныя пункты пасля дорогіх крокаў. Функцыя вярнення до роботы не павінна занова ставіць плату за той самы вызов LLM, калі аператар перапрыяўляе роботу да наступнага вузла.
EmployeeController.java similarity 0.94
CandidateController.java similarity 0.89
EndpointGuide.md similarity 0.87
EmployeeService.java similarity 0.82
ADR-17.md
Што робіць контекстны граф
Калі працуеце над стадзіяй «Што такое контекстны граф», спачатку запісайце умовы вярбунка: неабяжлівыя данні, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список контроля дапамагае заліцьварыць пазнейшыя змены ў кодзе. Документавайце як шлях успеху, так і шлях вяселення. Перапрыбуткі, людзкіе перакрыцця і обробка некоректных паведамленняў ёсць часткаю продукту, а не пазнейшым дапрацоўкам. Стварайце контрольныя пункты пасля дорогіх крокаў. Система вярнення не павінна зноў вырахоўваць адпаведную плата за вызов LLM, калі аператар перапрыбуе пазнейшы вузел. Калі працуеце над стадзіяй «Што такое контекстны граф», спачатку запісайце умовы вярбунка: неабяжлівыя данні, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список контроля дапамагае заліцьварыць пазнейшыя змены ў кодзе. Спрыймайце гэтую стадзію як умовы вярбунка між вхіднымі даннемі і перакананымі выходнымі рэзультатамі. Даўце назвы артыфактам, задайце критэрыяі успеху і адмовіцеся ад мовчанкавага частковага завершэння.
EmployeeEndpoint
EmployeeEndpoint
MUST_FOLLOW
EmployeeApiPattern
EmployeeApiPattern
REQUIRES
TenantIsolation
TenantIsolation
DEFINED_BY
ADR-17
ADR-17
INTRODUCED_AFTER
SecurityIncident-28
Запиты алгорытму пошуку вектараў:
Этап запитоў алгорытму пошуку вектараў працюе наякрацэ калі яго расследжваць як мерыемую паверхню. Перш чым расширваць масштаб, зафіксавайце адна ідеальная працэздатнась, адин случай неудачы і прыметкі па поверненню да пачатковага стану. Запісвайце часы выконання і косты токеноў або запитаў праза функцыональныя рэзультаты. Відразлівась костаў з самага пачатку запобегае неспакойным рахункам, калі працэс пераходзіць з дэмавайнага режыма ў спяльныя среды. Храніце стан графа ў простам і типаваным формате. Вкладзеныя блокі маскуюць інфармацыю пра тое, який вузел запісаў кожны поле, і спакшваюць продажчэ запуску пасля перарываў.
Запиты контэкстовага графа:
Граф контэксту працюе найэфектывней, калі яго спрыяваць як до меры. Зафіксавайте адны ідеальны прыклад роботы, адну ситуацыю неудачы і прыметкі па адвярненню перад расшырэнням масштаба. Зберагайте настройкі пазыроўна ад коду прыемліцеля. Файлы сяродавішча, хранільнікі секрэтных дадзеных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адбавляць контроль без неабяжнага чытання всего графа. Зберагайте стан графа у простам і типаваным формате. Вярнутыя блокі маскуюць інфармацыю пра тое, канфігурацыйны вузол запісаў якое поле, і спакоююць продажчыку пасля перарываў.
Але не выкидайце свой база дадзеных Vector
Этап «Але не кінуць» працюе найэфектывней, калі яго розглядаць як вимерную паверхню. Зафіксавце адны ідеальны прымер, адну справу з бягамі та прыметку па анулюванні змян перш чым расширваць масштаб. Дакументавайце як шлях успеху, так і шлях вяснавання разам. Перапрыбуткі, людзкія контраліны та обработка некоректных паведамленняў ёсць частью продукту, а не пасляднім дапрацоўкам. Храніце стан графа як просты та з типамі. Вярнутыя блокі маскуюць, який вузел запісаў канкрэтны поле, і спакоююць продовжэнне роботы пасля перарываў. Этап «Але не кінуць» працюе найэфектывней, калі яго розглядаць як вимерную паверхню. Зафіксавце адны ідеальны прымер, адну справу з бягамі та прыметку па анулюванні змян перш чым расширваць масштаб. Разглядвайце гэты этап як кантракт межа вхіднымі даннымі та перакананымі выходнымі рэзультатамі. Даўце назвы артыфактам, задаце критэрыя успеху та адмовіцеся ад мовчанкавага частковага завершэння.
Vector Search
+
Graph Traversal
+
Metadata Filters
+
Keyword Search
+
Agent Reasoning
Простая псіхалогічная модель
Для стадіі «Простая псіхалагічная модель» неабяжна ўзначыць вхідныя даны, адпаведальнага за крок і крэтыры завершэння пры перадзеі коду. Аперацыйныя працавнікі должны магчымае перадзеі крок з вядомай точкі контролю, не падозрываючы схованы стан. Запісваць час выконання і кост токеноў або запытаў праза функцыйнае рэзультат. Відкрытыя даны пра косцы запобегаюць неспакоўным рахункам, калі процес пераходзіць з дэмаверсіі ў спяльныя среды. Калі наступны крок — гэта код або вызов інструмента, лепш выкарыстоўваць структураваныя выходныя даны з перакананнем схэмы, чым вольныя тэкстовыя апісанні.
Графы контэксту ў репазітарыі Git
Для графа контексту ўнутрь стэйджа неабходна пазначыць вхідныя даны, адпаведальнага за крок і крэтыяры завершэння пры перадзеіснавленні коду. Аператары должны магчымае запускаваць крок з вядомай точкі контролю, не прабуючы спадарожваць схованы стан. Конфігурацыю трэба залічыць пазнаходзяцца за межамі коду прыкладнення. Файлы сераўнавання, хранільнікі секрэтных данных і флагі функцыяй павінны знаходзіцца ў адном месцы, якое аператары можаць пераглядаць, не чытаяўшы весь граф. Прызначыць людскія аправарэння для рэшэй, якія витрачаюць грошы або зменяюць даны у працэйнай сістэме. Падключэння ў час компілявання не є гарантыяй полнай адпаведнасці прыкладнення бізнес-трэбаванням.
employee-platform/
│
├── services/
│ ├── employee-service/
│ ├── payroll-service/
│ └── recruitment-service/
│
├── docs/
│ └── adr/
│
├── database/
│ └── migrations/
│
├── .agents/
│ ├── AGENTS.md
│ │
│ ├── skills/
│ │ └── add-end-point/
│ │ ├── SKILL.md
│ │ ├── templates/
│ │ └── references/
│ │
│ └── context/
│ ├── repository.yml
│ ├── architecture.yml
│ └── rules.yml
add-end-point
Проектаванне графа контексту рэпазітарыя
У стадії «Проектаванне контэкста рэпазітарыя» неабходна дэфініцыя вхідных даных, адміністратара крока і крэтэрыяў завершэння пры зміне коду. Аперацыйныя працавнікі должны магчымае перайсці на выкананне крока з вядомага пункта контролю, не спрабоўваючы здогадвацца пра заштынены стан. Неабходна задокументаваць як шлях успеху, так і шлях вярнення да нормальнага стану. Перапрыбуткі, людзкія пераказы і обробка некоректных паведамленняў є часткай продукту, а не елементамі пазнейшага дапрацоўкі. Неабходна людзкая аправа на тыя крокі, які ведуць да витрачання грошаў або зміны дадзэных у прыемнай сістэме. Працава ў час компілявання не є гарантыяй полнай адпаведнасці продукту бізнес-трэбованням. У стадії «Проектаванне контэкста рэпазітарыя» неабходна дэфініцыя вхідных даных, адміністратара крока і крэтэрыяў завершэння пры зміне коду. Аперацыйныя працавнікі должны магчымае перайсці на выкананне крока з вядомага пункта контролю, не спрабоўваючы здагадвацца пра заштынены стан. Спрыяйце таму, каб гэтае стадія выступала як контракт межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Назвайце всі элементы, задаць крэтэрыяў успеху і не падзеўляйцеся частым, некоректным завершэнням крока.
Repository
Module
Service
Class
Method
Endpoint
DatabaseTable
DatabaseColumn
Skill
ArchitecturePattern
Rule
Permission
ADR
Issue
PullRequest
Commit
Test
Repository CONTAINS Module
Module CONTAINS ClassController EXPOSES EndpointEndpoint CALLS ServiceService USES RepositoryRepository READS_FROM TableRepository WRITES_TO TableEndpoint REQUIRES PermissionClass TESTED_BY TestClass FOLLOWS PatternPattern DEFINED_IN ADRRule GOVERNED_BY ADRCommit CHANGES ClassPullRequest CONTAINS CommitIssue RESOLVED_BY PullRequestSkill APPLIES_TO EndpointSkill REQUIRES Rule
Маленькая прыкладная графіка
Калі вы працуеце над этапам «Маленькая прыкладная графіка», спачатку запісайце умовы викорыстання: неабяжлівыя даннэ, сигнал успеху і тое, што выканаецца у разы ўзелькая невыполненасць. Такі чарт дапамагае залічваць змяны ў кодзе чыста. Запісвайце час выконання і кост токеноў або запытаў праза функцыйнае рэзультат. Відразлівасць костаў з самага пачатку запобегае неспакойным рахункам, калі праця пераходзіць з дэмаверсіі ў спакульнаныя сераўсы. Зробіце перапаказ пасля дорогіх крокаў. Функцыя адновлення не должна зноў нараховваць косты за той самы вызыв LLM, калі аператар прабуе зноў выконаць пазнейшы ўзел.
EmployeeController
|
| CALLS
v
EmployeeService
|
| DELEGATES_TO
v
EmployeeHandler
|
| USES
v
EmployeeRepository
|
| WRITES_TO
v
HrEmployee
EmployeeController
|
| REQUIRES
v
EmployeePermission
EmployeeRepository
|
| FILTERS_BY
+----> TenantID
|
+----> OrganizationID
EmployeeController
|
| TESTED_BY
v
EmployeeControllerTest
add-end-point
|
| USES_PATTERN
v
EmployeeEndpointPattern
Як мы ствараемы гэтую графіку?
Калі працюеце над стадзіяй «Як мы будуем строить», спачатку запісайце контракт: неабяжлівыя даны, сігнал успеху і тое, што выходзіць у разе частковага неудачы. Такі список контроля дапамагае заліцвачыць змяны ў кодзе пазнейша. Зберагайце настройкі за межамі коду прыемліка. Файлы сераўнавання, хранальнікі секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаюць адбавіць аудыт без неабяжлівага чытання всей структуры. Ставьце контрольныя пункты пасля дорогіх крокаў. Система вярнення праблемы не должна занова ставіць плату за той самы вызов LLM, калі аператар перапрыяўляе роботу да наступнага вузла.
Java source
imports
method calls
Spring annotations
package structure
repository interfaces
SQL queries
DDL
configuration
test classes
Git history
ADR documents
AGENTS.md
SKILL.md
Фаза 1 — Статычны аналіз коду
Калі працуеце над стадзіяй 1 «Статычны код», спачатку запісайце контракт: неабяжлівыя данні, сигнал успеху і тое, што выканаецца у разе частковага нявыполнення. Такі список пераканаецца, што пазнейшыя змены коду будуць чыстымі. Документавайце як шлях успеху, так і шлях вярнення. Перапрыбуткі, людзкія контраліны і обработка некоректных паведамленняў ёсць часткай продукту, а не пазнейшым дапрацоўкам. Зробіце контрольную пазнаку пасля дорогіх крокаў. Система вярнення не павінна зноў вырахоўваць адпаведную плата за вызов LLM, калі аператар перапрыбуе пазнейшы вузел. Калі працуеце над стадзіяй 1 «Статычны код», спачатку запісайце контракт: неабяжлівыя данні, сигнал успеху і тое, што выканаецца у разе частковага нявыполнення. Такі список пераканаецца, што пазнейшыя змены коду будуць чыстымі. Спрыятлівае ставленне да гэтай стадзіі як да контракту межа даннімі і перакананымі выходамі. Дайце назву артыфактам, задаце перакананні на успех і адмовіцеся ад мовчазнага частковага завершэння.
@RestController
@RequestMapping("/employees")
public class EmployeeController {
private final EmployeeService employeeService; @PostMapping
public EmployeeResponse create(
@RequestBody EmployeeRequest request) {
return employeeService.create(request);
}
}
EmployeeController
TYPE
Controller
EmployeeController
EXPOSES
POST /employeesEmployeeController
CALLS
EmployeeService.create
Фаза 2 — Аналіз рэпазітарыя
Этап аналізу рэпазітарыя на Фазе 2 даўа найлепшыя рэзультаты, калі яго спрыяваць як меравальную плошчу. Зберагачыце адну ідеальную транскрыпцію, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштабы. Запісвайце часы выканання і кост токенаў або запытаў праза функцыйнае рэзультаты. Відразлівасць костаў з самага пачатку запобегае неспакойным рахункам, калі праця пераходзіць з дэмавайнага режыма ў спяльныя среды. Храніце стан графаў у простам і типаваным формате. Вярнутыя структуры маскуюць інфармацію пра тое, канкрэтны вузел запісаў канкрэтную палатку, і спакшваюць продажчык работі пасля перарываў.
public interface EmployeeRepository
extends JpaRepository<EmployeeEntity, Long> {
}
EmployeeRepository
OPERATES_ON
EmployeeEntity
@Entity
@Table(name = "HrEmployee")
EmployeeEntity
MAPS_TO
HrEmployee
Фаза 3 — Історыя Git
Этап 3 історыі Git працюе найэфектывней, калі яго спрыяваць як мерыемую паверхню. Запісаце адна ідеальная версія, адзін прыклад неудачы і прыметку па абяроŭненню перш чым расширваць масштаб. Храніце настройкі парадульна коду прыемлена. Файлы сяродавішча, хранальнікі секрэтных дадзеных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адбавляць контроль без неабясненага чытання всіх дадзеных. Храніце стан графа ў простам і типаваным формате. Вярнутыя блокі маскуюць, який вузел запісаў канкрэтны поле, і спакойваюць продаж чытання пасля перерываў.
Commit 812ac3
Message:
Add tenant filtering to employee repository.
Reason:
Prevent cross-tenant access.
EmployeeRepository
CHANGED_IN
Commit-812ac3
Commit-812ac3
PART_OF
PR-982PR-982
INTRODUCED
TenantIsolationRule
Этап 4 — Дакументы архітэктуры
Этап дакументацыі архітектуры 4-й фазы працюе найкраща, калі яго спрыяваць як меравальную плошчу. Зафіксавайце адны ідеальны прымер роботы, адзін кейс неудачы і прыметкі па адвярненню перад расшырэнням меж.
All employee mutations must pass through the EmployeeHandler.
EmployeeMutation
MUST_USE
EmployeeHandler
rule source:
ADR-17
5-я фаза — навыкі ШІ
Для стадіі AI Skills, яка належыць да фазы 5, пярэд зменым коду неабходна ўзначыць вхідныя даны, адпаведальнага за крок і крэтарыя выходу. Аператары должны магчымаць перзапуск кроку з вядомай точкі контролю, не спрабоўваючы з’ясаваць схованы стан. Запісваюць час выконання і кост токеноў або запытаў разам з функцыйнальнымі рэзультатамі. Відразлівасць костаў з самага пачатку запобегае неспакойным рахункам, калі процес пераходзіць з дэмовай среды ў спакульнаныя сераўсы. Неабходна людская апрацоўка тых крокаў, якія выкорыстоўваюць грошы або зміняюць даны ў працэсе виробніцтва. Праця пад час компілявання не ўзначае повнайсткі рэалізавання бізнес-функцыйяў.
.agents/skills/add-end-point/SKILL.md
Before creating an endpoint:
1. Identify the nearest existing endpoint pattern.
2. Resolve authentication and authorization rules.
3. Resolve tenant and organization isolation.
4. Identify service/orchestrator pattern.
5. Identify persistence pattern.
6. Identify required tests.
get_context(
task="create-endpoint",
domain="employee",
operation="create"
)
Сервіс Context Graph
Для стадіі The Context Graph Service неабяжна ўзначыць вхідныя даны, адпаведальнага за крок і критэрыя завершэння пры змены коду. Аператары должны магчымае перзапускать крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Конфігурацыю трэба залічыць пазначкай ад коду прыемленае. Файлы сераўнавання, хранілішчы секрэтных дадзеных і флагі функций должны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць, не чытаяўшы весь граф. Прызначыць людскія аправарэння для ребер, якія витрачаюць грошы або зменяюць даны у працэйнай сістэме. Прыўязка ў часе кампайлявання не адпавядае пачатковой цэлесапраўленасці.
AI Agent
|
v
Context API / MCP Server
|
+--------> Graph Database
|
+--------> Vector Database
|
+--------> Git Repository
find_entity
get_neighbors
find_path
get_architecture_context
get_security_context
get_database_context
get_change_history
get_similar_implementations
get_context_for_task
record_decision
get_context_for_task(
repository="employee-platform",
skill="add-end-point",
task="create reimbursement approval endpoint"
)
Какія базы дадзеных графаў нам выкорыстоўваць?
Для стадіі «Калькольная база дадзэных, якая павінна быць выбрана» неабходна ўзначэння вхідных дадзеных, адпаведальнага за крок і крэтарыяў завершэння працы перад зменым коду. Аперацыйныя працавнікі павінны магчымае перазапускаць крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Неабходна аддзекуванне як шляха успеху, так і шляха вярнення да нормальнага стану. Перапрыбуткі, людзкія пераказы і обробка некоректных паведамленняў ёсць часткай продукту, а не пасляднім дапрацоўкам. Неабходна людзкая аправарэнне для роўнаў, якія выкарыстоўваюць грошы або зміняюць даны для працы. Працэс кампілявання не ўзначае повнайшага адпаведнення продукту бізнес-трэбованням. Для стадіі «Калькольная база дадзэных, якая павінна быць выбрана» неабходна ўзначэння вхідных дадзеных, адпаведальнага за крок і крэтарыяў завершэння працы перад зменым коду. Аперацыйныя працавнікі павінны магчымае перазапускаць крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Спрыяйце таму, каб гэтая стадія выступала як контракт межа вхіднымі дадзенымі і перакананымі выходнымі рэзультатамі. Назвайце всі элементы, узначьце крэтарыяў успеху і не прабуйце прыймаць часткова завершаныя рэзультаты без падтверджэння.
JSON files
+
NetworkX
+
SQLite
Абсалютна простая рэпрэзентацыя на кшталт Neo4j
Калі працуеце з етапам «Абсалютна простая рэпрэзентацыя на кшталт Neo4j», спачатку запісайце умовы викорыстання: неабяжлівыя даннэ, сигнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список дапамагае заліцьваты змяны ў кодзе. Запісуйце час виконання і кост токеноў або запытаў разам з функцыйнальнымі рэзультатамі. Відразлівасць костаў з самага пачатку запобегае неспакойным рахункам, калі праця пераходзіць з дэмаверсіі ў спакульнаныя сераўры. Стварайце контрольныя пункты пасля дорогіх крокаў. Функцыя вярнення не должна зноў нараховваць косты той самай вызову LLM, калі аператар перапрыяўляе роботу да наступнага вузла.
CREATE (:Class {
name: "EmployeeController",
type: "Controller"
});
CREATE (:Service {
name: "EmployeeService"
});CREATE (:Repository {
name: "EmployeeRepository"
});
MATCH (c:Class {name:"EmployeeController"}),
(s:Service {name:"EmployeeService"})
CREATE (c)-[:CALLS]->(s);
MATCH (s:Service {name:"EmployeeService"}),
(r:Repository {name:"EmployeeRepository"})
CREATE (s)-[:USES]->(r);
Запытанні графа
Калі працюеце над стадзіяй «Запыткі да графа», спачатку запісайце контракт: неабяжлівыя даны, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список контроля дапамагае заліцвачыць змяны ў кодзе пазнейша. Зберагайце настройкі за межамі коду прыемліка. Файлы сераўнавання, хранілішчы секрэтных данных і флагі функцый крануцца на аднам месцы, якое аператары можаць пераглядаць без неабяжлівага чытання всего графа. Стварайце контрольныя пункты пасля дорогіх крокаў. Функцыя вярнення роботы не должна занова ставіць плату за той самы вызов LLM, калі аператар перапрыяўляе роботу да наступнага вузла.
MATCH path =
(endpoint:Endpoint)-[*1..4]-(context)
WHERE endpoint.domain = "employee"
RETURN path
Controller
Service
Handler
Repository
Table
Permission
Tenant Rule
Tests
ADR
Лепшая архітектура: гібрыдны метод выкарыстоўвання дадзеных
Калі працуеце над стадзіяй «A Better Architecture Hybrid», спачатку запісайце угоду: неабяжлівыя данні, сигнал успеху і тое, што выходзіць у разе частковага абякання. Такій чарткі памагае заліцьваты чыстасцю будучых змян у кодзе. Документавайце як шлях успеху, так і шлях вяснавання. Перапрыбуткі, людзкія контралі і обработка некоректных паведамленняў ёсць часткай продукту, а не чымось, што дадаецца пазней. Змяроўваюце рэкалі на фіксаванай сэтке запытаў прычым падбір прапаноў. Частае змена прапаноў рэдка калі вярнуе слабую эфектыўнасць адзысквання інформаціі. Калі працуеце над стадзіяй «A Better Architecture Hybrid», спачатку запісайце угоду: неабяжлівыя данні, сигнал успеху і тое, што выходзіць у разе частковага абякання. Такій чарткі памагае заліцьваты чыстасцю будучых змян у кодзе. Спрэтавайцеся да гэтай стадзіі як да угоды межа даннімі і перакананымі выходамі. Дайце назвы артыфактам, задаце правілы пераканання успеху і адмовіцеся ад тыхоўскага частковага завершэння.
User Request
|
v
Context Retriever
|
+--------------+--------------+
| | |
v v v
Vector Graph Keyword
Search Traversal Search
| | |
+--------------+--------------+
|
v
Context Ranking
|
v
Agent Context
|
v
LLM
Проблема бюджэту контексту
Проблема бюджэту контексту працюе наявнасць калі яе расследжваць як вимерную структуру. Запісаўце адна ідеальная версія, адзін прыклад неудачы і запіс пра вярненне да поперадньяго стану перш чым расширваць масштабы. Запісвайце час выканання і кост токеноў або запытаў праза функцыйнае рэзультат. Відразлівае паказанне костаў з самага пачатку запобегае неспакойным рахункам, калі процес пераходзіць з дэмаверсіі ў спяльныя среды. Храніце стан графа ў простам і типаваным формате. Вкладзеныя структуры маскуюць інфармацыю пра тое, який вузел запісаў кожны поле, і спакшваюць продажчык працы пасля перерываў.
Repository:
8 million tokens
Controller conventions
Service convention
Security rule
Two repositories
One ADR
Three tests
Total:
18,000 tokens
Контекстны граф + Навыкі агента
Этап скілу Context Graph Agent працюе найэфектывней, калі яго розглядаць як вимерную паверхню. Зафіксавце адна ідеальная транскрыпцыя, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць сферу дзеяння. Зберагаюце настройкі пазначыце за межамі коду прыемленае. Файлы сераўнавальнага сераўсу, хранілішчы секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адбавляць контроль без неабяжнага чытання всіх данных. Зберагаюце стан графа ў простам і типаваным формате. Вярнутыя структуры данных маскуюць інфармацыю пра тое, калькі вузел запісаў калькі поле, і спакойваюць працэс пасля перарываў.
Developer
|
v
AI Agent
|
v
add-end-point Skill
|
v
Context Graph Query
Developer
|
| "Create employee endpoint"
v
AI Agent
|
| reads
v
.agents/skills/add-end-point/SKILL.md
|
| SKILL.md says:
| "Before generating code,
| call get_task_context"
v
MCP Tool
get_task_context(...)
|
v
Context Graph Service
|
+---- Neo4j / Graph DB
|
+---- Vector Search
|
+---- Git metadata
|
v
Relevant Context
|
v
AI Agent
|
| follows retrieved rules
v
Generate / modify code
Nearest endpoint:
LeaveRequestController
Controller pattern:
@RestController
constructor injectionService pattern:
interface + implementationArchitecture:
Controller
-> Service
-> Handler
-> RepositorySecurity:
LEAVE_VIEWTenant rules:
OrganizationID + TenantIDPersistence:
HrLeaveBalanceTesting:
ControllerTest
ServiceTest
RepositoryITArchitecture decision:
ADR-42
Потым агент генеруе код
Этап «The Then the Agent Generates» працюе найкраща, калі яго розглядаць як параметрызаваную плошчу. Зафіксавце адны ідеальны прымер роботы, адну справу з бягамі та прыметку па вярнэнню да пачатковага стану пры расшырэнні масштаба. Дакументавце як шлях успеху, так і шлях вярнэння да нормальнага стану. Перапрыбуткі, людзкія контраліны та обработка некоректных паведамленняў є часткай продукту, а не элементамі пазнейшага доўрабатвання. Храніце стан графа ў простам і типаваным формате. Вярнутыя структуры дакументаў маскуюць інфармацыю пра тое, який вузел запісаў кожны поле, і спакшуюць продовжэнне роботы пасля перарываў.
LeaveBalanceController
LeaveBalanceRequest
LeaveBalanceResponse
LeaveBalanceService
LeaveBalanceServiceImpl
LeaveBalanceHandler
LeaveBalanceRepository
LeaveBalanceProjection
LeaveBalanceException
LeaveBalanceControllerTest
LeaveBalanceServiceTest
LeaveBalanceRepositoryTest
Этап «The Then the Agent Generates» працюе найкраща, калі яго розглядаць як параметрызаваную плошчу. Зафіксавце адны ідеальны прымер роботы, адну справу з бягамі та прыметку па вярнэнню да пачатковага стану пры расшырэнні масштаба. Разглядвайце этап як кантракт межа вхіднымі даннымі та перакананымі выходнымі рэзультатамі. Даўце назвы дакументам, задаце критэрыя успеху та адмовіцеся ад мовчанкавага частковага завершэння роботы.
Does the endpoint follow the required architecture?
YES.Does it apply security?YES.Does repository filtering include TenantID?YES.Does it include OrganizationID?YES.Are mandatory tests present?YES.
Стартаванне рэпазітарыя
Для стадіі Bootstrap у рэпазітарые неабяжна практычна адзначыць вхідныя данні, адпаведальнага за крок і критэрыі завершэння пры змяне коду. Аператары должны магчымаць перзапуск крока з вядомай точкі контролю, не падозрываючы схованы стан. Запісваць трэба час выконання і кост токена або запыту разам з функцыйнальнымі рэзултатамі. Відразы коста з самага пачатку запобегае неспакоўным рахункам, калі процес пераходзіць з дэмовай среды ў спяльнаваныя сераўеры. Неабяжна ўвайсці людзкую апраўду для тых крокаў, якія витрачаюць грошы або зменяюць данні ў працоўный сераўер. Прыўязка на час компіляцыі не ўзначае повнайсткавасці бізнес-процэса.
bootstrap-context
2-3 representative endpoints
architecture
build files
framework versions
dependency injection
security
database patterns
testing
exception handling
transactions
module boundaries
Repository
USES
Java17
Repository
USES
SpringBoot3Endpoint
FOLLOWS
Controller-Service-Handler-RepositoryDatabaseQuery
MUST_INCLUDE
TenantIDDatabaseQuery
MUST_INCLUDE
OrganizationID
Навыкі становяцца значна меншымі
У стадії «Навыкі стаюць значна меншымі» неабяжна пазначыць вхідныя даны, адміністратара крока і критэрыя завершэння пры перадзеіснавленні коду. Аператары должны магчымаць перзапуск крока з вядомай точкі контролю, не спрабоўваючы здогадвацца пра схованы стан. Конфігурацыю трэба залічыць параду ад коду прыкладнення. Файлы сераўіса, хранальнікі секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць, не чытаяўшы весь ланцуг задач. Для рэшэнняяў, якія выкарыстоўваюць грошы або зміняюць даны у працэсе, неабяжна выкарыстоўваць пацэнтаванне чалавека. Підключэння пад час компіляцыі не ўзначае повнасці бізнес-процэсу.
For employee APIs use EmployeeHandler.
For payroll APIs use PayrollOrchestrator.For recruitment APIs use ActionHandler.For employee APIs tenant filtering happens...For payroll APIs...
1. Understand the requested endpoint.
2. Query the repository Context Graph.3. Resolve:
- architecture pattern
- closest implementation
- security
- data ownership
- persistence
- testing requirements4. Generate code.5. Validate generated changes against graph constraints.6. Record newly confirmed repository knowledge.
Навыкі падказываюць агенту ЯК
Для стадіі «Skills Tell the Agent» неабяжна ўзначыць даннэ, якія будуць вводзіцца, адпаведальнага за шаг і крэтыяры завершэння пры перадзеі коду. Аперацыйныя працавнікі должны магчымае запускаць шаг з вядомай точкі контролю, не падозрываючы прыхованы статус. Неабяжна задокументаваць як «шчаслівы» шлях, так і шлях вярнення. Перапрыбуткі, людзкіе перакрыцця і обробка некоректных паведамленняў ёсць часткай продукту, а не пасляднім дапрацоўкам. Неабяжна прыняць людзкую згоду для тых крокоў, якія выкарыстоўваюць грошы або зменяюць даннэ ў працоўным режыме. Працэс кампілявання не ўзначае повнайшага адпрацоўвання продукту з точкі зору бізнеса.
Контэкстны граф паведамляе агента, ЧАГО ТУТ НЕЁСУЦЬ ПРАВДУ
Кабы Контэкстны граф паказаў стадію, неабходна перад змянай коду задаць вхідныя даны, абавесця крока і критэрыі завершэння. Аперацыяныя працавнікі должны магчымае перадзваніць крок з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан. Лепш выбіраць маленькія, тэставаныя елементы замест большых скрыптаў. Калі крок не выйшоў, прычына неудачы должна вказываць на адну конкрэтную абавесцю, а не на заплутаны процес. Прабачаць людзкую апраўдку для тых канектаў, якія выкарыстоўваюць грошы або зміняюць даны у працэсе виробніцтва. Праця ў часе компілявання не абавесцвае полнайсткі бізнес-процэса.
Контэкстныя графы і системы з калькамі агентаў
Для стадзій Context Graphs і Multi-Agent неабяжна ўскладненне вхідных дадзей, адпаведальнага за кожны крок і крэтарыяў завершэння працы перад змінайом коду. Аператары должны магчымае запускіць крок з вядомай точкі контролю без неабяжнага вычыслення схованых станоў. Спрыяйце цій стадзіі як кантракту межа вхідных дадзей і перакананых выходных рэзультатаў. Даць назвы артыфактам, ускладніць перакананняя пра успех і адмовіцца ад беззвучнага частковага завершэння. Забезпечыце людскія падтверджэнняя для рэласаў, якія выкарыстоўваюць грошы або зміняюць даны праработкі. Компіляцыйныя налашчэнняя не ўзроўнаўцуюцца з абсягам бізнес-працы.
Architecture Agent
Security Agent
Backend Agent
Testing Agent
Database Agent
Reviewer Agent
duplicate work
different conclusions
large token usage
conflicting decisions
Context Graph
/ | \
/ | \
v v v
Backend Security Testing
Agent Agent Agent
Endpoint requires FINANCE_WRITE
Context Graphs могу выучыцца з Pull Requests
У стадії, калі графы контэксту можаюць выучвацца, пярш чым зменіць код, неабходна ўзгадка пра вхідныя даны, адпаведальнага за крок і крэтарыя выходу. Аператары должны магчымаць перзапуск кроку з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан. Запісвайце час выконання і кост токеноў або запытаў праза функцыйнае рэзультат. Відкрытыя даны пра косцы запобегаюць неспакоўным рахункам, калі парадок пераходзіць з дэмовай среды ў спяльную. Паставіце людзкую апраўдку на рэшты, якія витрачаюць грошы або зменяюць даны у працэсе. Працэс складання коду не ўзначае повнайсткі рэалізавання бізнес-функцыйяў.
repository.findByEmployeeId(employeeId);
EmployeeRepositoryQuery
MUST_FILTER_BY
TenantID
EmployeeRepositoryQuery
MUST_FILTER_BY
OrganizationIDRule
LEARNED_FROM
PR-11882
Граф контэксту — гэта не мозг LLM
Для стадіі A Context Graph Is неабяжна прадзеўкаванне вхідных дадзеных, абяранні адпаведальнага за крок і крэтарыяў завершэння працы перад зменым коду. Аперацыйныя працавнікі павінны магчымае перапрацаваць крок, выкорыстоўваючы вядомы пункт перапаўтку, без неабяжнага вычыслення скрытых станоў. Конфігурацыю трэба захавваць праза код аплікацыі. Файлы сяродавішча, хранальнікі секрэтных дадзеных і флагі функцый павінны знаходзіцца ў адном месцы, якое аперацыйныя працавнікі могу пераглядаць, не чытаючы весь граф. Калі наступны крок — це код або вызов інструмента, лепш выкарыстоўваць структураваныя выходныя данні з паўерачаннем схэмы, чым вольныя тэкстовыя апісанні.
LLM
=
Reasoning Engine
Context Graph
=
Structured MemoryVector Database
=
Semantic Memory SearchSkills
=
ProceduresTools
=
Actions
AI Agent
|
+---------+---------+
| | |
v v v
Skills Context Tools
Graph
|
+-------+-------+
| |
v v
Vector Graph
Search Store
Context Graph проты Fine-Tuning
Для стадіі Context Graph проты Fine-Tuning неабяжна прадзефінаваць вхідныя даны, адпраўніка крока і крэтыяры завершэння пры перадзеўці коду. Аперацыйныя працавнікі должны магчымае запускаць крок з вядомай точкі контролю без неабяжнага адгадвання захаванога стану. Неабяжна задокументаваць як шлях успеху, так і шлях вярнення да нормальнага стану. Перапрыбуткі, людзкія пераказы і обробка некоректных паведамленняў ёсць часткай продукту, а не пасляднім дапрацоўкам. Неабяжна прысваяць людзкую згоду тым канектам, якія витрачаюць грошы або зменяюць даны для працы продукту. Підключэння пад час компілявання не ўзроўнаўваецца з повнайасцю бізнес-функцый. Для стадіі Context Graph проты Fine-Tuning неабяжна прадзефінаваць вхідныя даны, адпраўніка крока і крэтыяры завершэння пры перадзеўці коду. Аперацыйныя працавнікі должны магчымае запускаць крок з вядомай точкі контролю без неабяжнага адгадвання захаванога стану. Спрыяць гэтай стадіі як кантракту межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Прадацаваць назвы артыфактов, прадзефінаваць пераказы успеху і адмовляцца ад бяспечнага частковага завершэння.
OldRule
status = deprecated
NewRule
status = active
Граф контэкста протыя Ўжаснага запросу
Калі працуеце над этапам «Граф контэкста протыя Ўжаснага запросу», спачатку запісайце умовы: неабяжлівыя даннэ, сігнал успеху і тое, што выходзіць пад частыя неудачы. Такі список дапамагае заліцьвараць будучыя змены ў кодзе. Запісвайце час выканання і кост токеноў або запытача праза функцыйнае рэзультат. Відразлівасць костаў з самага пачатку запобегае неспакойным рахункам, калі праця пераходзіць з дэмаверсіі ў спакульнаныя сераўсы. Зберагачвайце стабільныя інструкцыі системы і схемы інструментаў. Перадзесланне ідэнтычных прамаўляючых частак — частая прычына збытка ресурсаў.
AGENTS.md
= 40,000 lines
Task
|
v
Relevant Subgraph
|
v
Prompt
Entire Organization
|
v
Prompt
Як размістіць першую версію
Калі працуеце над этапам «Як адмініструвацыя развёртывання», спачатку запісайце умовы контракту: неабяжлівыя даны, сигнал успеху і тое, што выходзіць пад частковыя неудачы. Такі список контроля дапамагае заліцвачыць змяны ў кодзе па правдзе. Зберагайце настройкі за межамі коду прыемліка. Файлы сераўнавання, хранілішчы секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адбавляць аудыт без неабяжлівага чытання всей структуры. Стварайце контрольныя пункты пасля дорогіх крокаў. Система вярнення роботы не должна занова ставіць плату за той самы вызов LLM, калі аператар перапрыяўляе роботу да наступнага элемента.
Repository:
employee-service
Skill:
add-end-point
Module
Class
Endpoint
Service
Repository
Table
Rule
Permission
Test
ADR
CONTAINS
EXPOSES
CALLS
USES
WRITES_TO
READS_FROM
REQUIRES
TESTED_BY
FOLLOWS
DEFINED_IN
Рэкамендаванае развёртывання
Калі працюеце над стадзіяй «Рэкамендаваная дыстанцыя развіцця», спачатку запісайце умовы кантракту: неабяжлівыя даны, сігнал успеху і тое, што выходзіць пад частыя неудачы. Такі список пераканае ў тым, што пазнейшыя змены коду будуць чыстымі. Документавайце як шлях успеху, так і шлях вярнення да нормы. Перапрыбуткі, людзкія контралі і обработка некоректных паведамленняў є частью продукту, а не пазнейшым дапрацоўкам. Зробіце контрольную пазнаку пасля дорогіх крокаў. Програма не должна зноў выклікаць той самы кантакт з LLM, калі аператар перапрыбуе пазнейшы вузел.
Git Repository
|
|
v
Repository Indexer
|
+------ Java Parser
|
+------ Git Parser
|
+------ Markdown Parser
|
+------ SQL Parser
|
v
Context Graph DB
|
+------ Vector Index
|
v
Context Service / MCP
|
v
AI Coding Agent
|
v
Repository Skills
Пашагова адчыніце граф
Калі працуеце над этапам «Апдэйт графа пасляўзовым чынам», спачатку запісайце кантракт: неабходныя вхідныя даны, сігнал успеху і тое, што выходзіць у разе частковага невыпання. Такі список пераконтроўкі дапамагае заліцвачыць пазнейшыя змены ў кодзе. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшае, невыпанне должна паказваць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцюг задач. Зробіце пераконтроўку пасля дорогіх крокаў. Функцыя адновлення не должна зноў ставіць плату за той самы вызов LLM, калі аператар праканае пазнейшы вузел.
EmployeeController.java
EmployeeService.java
ADR-42.md
git diff HEAD~1
changed files
|
v
re-index
|
v
update graph
Контэкст должен мець паверунак
Калі працуеце на стадзіі «Контэкст должен быць надзеяным», спачатку запісайце контракт: неабяжлівыя даннэ, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список перакладзець пазнейшыя змены коду ў правільны направленні. Спрэцьвуйце да гэтай стадзіі як да контракту межа даннемі і перакананымі выходамі. Дайце назвы элементам, задаце критэрыя успеху і не прабуйце прыймаць часткова завершанне без паведамлення. Зробіце пераконтроль пасля дорогіх крокаў. Система вярнення не должна зноў ставіць плату за той самы вызов LLM, калі аператар прабуе зноў запрацаваць з пазнейшым вузлам.
EmployeeController
CALLS
EmployeeService
confidence = 1.0
source = static-analysis
Employee APIs
PROBABLY_REQUIRE
ManagerPermission
confidence = 0.62
source = llm-inference
FACT
OBSERVATION
INFERENCE
DECISION
RULE
Людзі должны магчыма быць карэктаваць граф
Калі працуеце над стадіяй «Людзі павінны магчымаць», спачатку запісайце угоду: неабяжлівыя даны, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список перакладоў заходзіць пазнейшыя змены коду чыстымі. Запісвайце час выканання і кост токенаў або запытаў праза функцыйнае рэзультат. Відкрытыя даны пра косцы з’являюцца раніце, таму не будзе неспадзянак у вопысах, калі працэс пераходзіць з дамавайна да спяльных сэрвераў. Зрабіце перапаказ пасля дорогіх крокаў. Система вярнення не павінна зноў нарахоўваць косты той самай вызову LLM, калі аператар прабуе зноў запрацаваць пазнейшы вузел.
Payroll APIs use Handler architecture.
HandlerPattern
status = deprecated
OrchestratorPattern
status = active
Большая ідея: ад пошуку ў рэпазітарыі да разумення рэпазітарыя
Калі працуеце над стадіяй «The Bigger Idea From», спачатку запісайце угоду: неабяжлівыя даны, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список контроля дапамагае заліцвачыць змяны ў кодзе пазнейша. Зберагайце настройкі за межамі коду прыемліка. Файлы сераўнавання, хранільнікі секрэтных данных і флагі функцый належаць у аднам месца, куды аператары можаць адбавляць аудыт без неабяжлівага чытання всей структуры. Ставьце контрольныя пункты пасля дорогіх крокаў. Система вярнення працы не должна занова ставіць плату за той самы вызов LLM, калі аператар перапрыяўляе роботу да наступнага вузла.
Question
|
v
Search Files
|
v
Read Files
|
v
Generate Code
Question
|
v
Understand Task
|
v
Identify Relevant Entities
|
v
Traverse Architecture
|
v
Recover Rules
|
v
Recover History
|
v
Recover Decisions
|
v
Build Context
|
v
Execute Skill
|
v
Validate Result
|
v
Record Learning
Аналагія з старшым інжынерам
Калі працуеце над стадзіяй «Аналагія высокакваліфікаванага інжынера», спачатку запісайце угоду: неабяжлівыя данні, сигнал успеху і тое, што выходзіць у разе частковага абярэння. Такі список пераканальвае ў тым, каб пазнейшыя змены коду былі чыстымі. Документавайце як шлях успеху, так і шлях вярнення да нормальнага стану. Перапрыбуткі, людзкія контрольныя пункты і обработка некоректных поведань ўскладнень ёсцю частью продукту, а не пазнейшым допрацоўкам. Зробіце перапытку пасля дорогіх крокаў. Система вярнення не павінна знову ставіць плату за той самы вызов LLM, калі аператар перапрыбуе пазнейшы вузел. Калі працуеце над стадзіяй «Аналагія высокакваліфікаванага інжынера», спачатку запісайце угоду: неабяжлівыя данні, сигнал успеху і тое, што выходзіць у разе частковага абярэння. Такі список пераканальвае ў тым, каб пазнейшыя змены коду былі чыстымі. Спрыятлівайце гэтай стадзіі як угоды межа даннімі і перакананымі выходамі. Дайце назвы элементам, задаце критэрыя успеху і адмовіцеся ад мовчанкавага частковага завершэння.
Гэтае і ёсць справжняя обяцанне
Этап «Гэта ўсё, што ёсць рэальнае» працуе наякшым чынам, калі яго спрыяваць як вимерную паверхню. Запісайте адны «золаты» прыклад, адну справу з бягам і прыметку пра вярненне да пачатковага стану перш чым расширваць масштаб. Запісвайте часы выконання і косцты токеноў чыста запытаў пад функцыйнальнымі рэзультатамі. Відразлівае паказанне косцоў з’являецца рана, таму не будзе неспакою з рахункамі, калі праця перайдзе з дэмаверсіі ў спакульнаныя сераўысы.
Будучы репазітарый можа выглядаць зусім інакш
CODE
What the system does.
SKILLS
How agents should perform work.CONTEXT GRAPH
What the agent should understand about this repository.
my-platform/
│
├── services/
│
├── database/
│
├── docs/
│
├── tests/
│
│
├── AGENTS.md
│
├── .agents/
│ │
│ ├── skills/
│ │ ├── add-end-point/
│ │ ├── fix-bug/
│ │ ├── create-migration/
│ │ └── review-pr/
│ │
│ └── context/
│ ├── graph-schema.yml
│ ├── rules.yml
│ └── bootstrap.yml
│
└── context-graph/
├── indexer/
├── extractors/
├── graph-api/
└── validation/
Ішчыны прыклад
TASK
Create reimbursement endpoint.
DOMAIN
Finance / Employee.PATTERN
ExpenseController.ARCHITECTURE
Controller -> Service -> Orchestrator -> Repository.AUTHENTICATION
Session authentication required.AUTHORIZATION
CREATE_REIMBURSEMENT.TENANCY
OrganizationID + TenantID mandatory.DATABASE
HrReimbursement.TRANSACTION
Orchestrator owns transaction.IMPORTANT HISTORY
Direct reimbursement status mutation caused incident FIN-822.RULE
Use ReimbursementWorkflow.TESTING
Controller + Service + Repository tests required.REFERENCE PR
PR-11822 implemented similar Expense workflow.
Заключныя меркі
LLM
gives the agent intelligence.
Skills
give the agent procedures.Tools
give the agent hands.Vector search
helps the agent find things.Context Graph
helps the agent understand how those things are connected.Decision history
helps the agent understand why.