Графы кантэксту для AI-агентаў: памяць старэйшага інжынера
Графы кантэксту даюць AI-агентам памяць старэйшага інжынера: чаму пошуку ў вектарнай базе і большага акна кантэксту недастаткова.
Крыніцы: Context Graphs for AI Agents: Giving AI the Memory of a Senior Engineer
Чаму наступнам паколенню агентаў 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.