agent foundation kit — სასტარტო ძრავა Claude Code-ის პროექტებისთვის

ეს არის მზა სამუშაო გარემო (ძრავა) ახალი პროექტისთვის, რომელსაც Claude Code აშენებს. თავად პროდუქტი აქ ჯერ არ არის — აქ არის ის, რაც უზრუნველყოფს, რომ აგენტმა ყოველ ახალ სესიაზე იცოდეს, სად გაჩერდით; არაფერი დაამტკიცოს შენს მაგივრად; საიდუმლო გასაღებებს არ შეეხოს; და ყოველი შედეგი მანქანამ შეამოწმოს. GitHub-ზე დააჭირე Use this template, და შენი ახალი პროექტი პირველივე დღიდან ამ წესებით დაიწყება. რას ვაშენებთ — intent.md; სად ვართ — progress.md; რა რიგით მივდივართ — plan.md; როგორ ვმუშაობთ და სად წყვეტ შენ — process.md.

როგორ მუშაობს — ერთი სურათით

წარმოიდგინე სამშენებლო ობიექტი, სადაც ბრიგადირი (Claude) ყოველ დილით მეხსიერებადაკარგული მოდის. რომ სამუშაო არ აირიოს, ობიექტზე ოთხი რამ არსებობს:

1. მაგიდაზე დადებული დღის ფურცელი — progress.md-ის „ახლა", plan.md-ის მიმდინარე ფაზა და tasks/todo.md-ის „ახლა / შემდეგი" (Claude-ის კონკრეტული დავალებები). Claude-ს ის ავტომატურად ეწოდება ყოველი სესიის დასაწყისში და ყოველი compact-ის (საუბრის ავტომატური შეკუმშვის) შემდეგ.
2. სამუშაო ჟურნალი და არქივი — ყოველ სესიას თავისი ჩანაწერი (ეპიზოდი) აქვს memory/episodes/-ში. სესიის ბოლოს /session-close ყველაფერს სწორ ადგილებზე ანაწილებს; თუ დაგავიწყდა, სესიის დახურვისას ფონური პროცესი თავად შეაჯამებს. მეხსიერების სრული რუკა — memory/README.md.
3. შენი ხელმოწერა — განზრახვა, სპეციფიკაცია (spec — ფუნქციის ზუსტი აღწერა), გეგმა და არქიტექტურული გადაწყვეტილება (ADR) ძალაში შედის მხოლოდ მაშინ, როცა შენ დაამტკიცებ /approve-ით. Claude-ს ამის გაკეთება არ შეუძლია — ამას guard (ავტომატური დარაჯი) ბლოკავს, gate კი ამოწმებს.
4. ტექნიკური ზედამხედველი — კარიბჭეები (gates — მანქანური შემოწმებები), რომლებიც ყოველ commit-ზე (შენახვის წერტილზე) და ყოველი პასუხის ბოლოს ეშვება და იჭერს იმას, რასაც მოდელი გამოტოვებს. თავად შემოწმებებიც მოწმდება: დრილი თითოეულს განზრახ „ტეხს" და ამოწმებს, რომ დაიჭირა.

ყველაფერი ჩვეულებრივი ტექსტური ფაილია, ერთმანეთთან ბმულებით — ამიტომ Obsidian-ში გრაფად ჩანს, Claude კი იმავე გრაფს tools/context_graph.py-ით ხედავს.

როგორ დავიწყო — სამი ნაბიჯი

1. შექმენი შენი პროექტი ამ შაბლონიდან. GitHub-ზე, ამ გვერდის თავში, დააჭირე Use this template → Create a new repository, დაარქვი სახელი და ჩამოტვირთე კომპიუტერში (git clone https://github.com/<შენი-სახელი>/<რეპოს-სახელი>.git ან GitHub Desktop-ით).
2. გახსენი იმ საქაღალდეში Claude Code — ტერმინალში claude ან VS Code-ის Claude Code გაფართოება — და საქაღალდეს ნდობა მიეცი (trust). დანარჩენს ძრავა თავად აწყობს: git-ს, commit-ის შემოწმებებს და ხელსაწყოების შემოწმებას. setup-ის ბრძანებები არ გჭირდება.
3. მისწერე შენი იდეა ჩვეულებრივი სიტყვებით — მაგალითად: „მინდა გავაკეთო ვებსაიტი ჩემი საცხობისთვის: მენიუ, ფასები და ონლაინ შეკვეთა". ეს შეიძლება იყოს საიტი, თამაში, აგენტი, ავტომატიზაცია — ნებისმიერი რამ.

ამის შემდეგ Claude იდეას ჩაიწერს და ეტაპობრივად გაგიძღვება: ჯერ რამდენიმე კითხვა (განზრახვა), მერე ზუსტი აღწერა (სპეციფიკაცია), მერე — რით აშენდეს (არქიტექტურა), მერე გეგმა და აშენება, ბოლოს კი მუშა შედეგის ჩვენება. ყოველ ეტაპზე გეტყვის, რა მოდის შემდეგ, სტატუსის ზოლში (ეკრანის ქვედა ხაზები) კი 🧭-ით ჩანს, სად ხარ. მთავარ დოკუმენტებს Claude გთავაზობს, ძალაში კი მხოლოდ შენი ბრძანებით შედის — მაგალითად /approve intent; ზუსტ ბრძანებას ყოველ ჯერზე თვითონ გეტყვის. პროექტის ყოველ ტიპს — საიტს, თამაშს, AI აგენტს, ავტომატიზაციას და სხვას — თავისი სახელმძღვანელო აქვს (docs/guides/): მისი მიხედვით Claude გისვამს კითხვებს, გთავაზობს, რით აშენდეს, პირველ ვერსიას მცირე ზომისას ტოვებს და შედეგს გაჩვენებს.

რა უნდა იყოს კომპიუტერზე

ძრავა მუშაობს Windows-ზე (10 ან 11), macOS-სა და Linux-ზე. საჭიროა სამი რამ. git: Windows-ზე — Git for Windows (git-scm.com; მასთან ერთად დგება Git Bash, რომლითაც hook-ები, ანუ ავტომატური ჩამრთველები, ეშვება), macOS-ზე — xcode-select --install ან brew install git, Linux-ზე — sudo apt install git. Python 3.12 ან უფრო ახალი: Windows-ზე — python.org ან winget install Python.Python.3.12, macOS-ზე — brew install [email protected], Linux-ზე — sudo apt install python3.12 (სხვაგან uv python install 3.12). და Claude Code შენი Claude-ის გამოწერით. Python-ს ძრავა თავად პოულობს (.claude/hooks/py.sh), ამიტომ არ აქვს მნიშვნელობა, მას py ჰქვია თუ python3. თუ რომელიმე აკლია ან git-მა შენი სახელი და ელფოსტა არ იცის, Claude პირველივე სესიაზე გეტყვის და დაყენებას შემოგთავაზებს — შენი „კი"-ს შემდეგ. gitleaks (საიდუმლო გასაღებების მაძიებელი) სასურველია, მაგრამ აუცილებელი არ არის: მის გარეშე commit-ებს ძრავის საკუთარი, უფრო სუსტი სკანერი ამოწმებს და შედეგში ამას პირდაპირ წერს. სურვილისამებრ: VS Code (სამუშაოდ) და Obsidian (obsidian.md — პროექტის გრაფის სანახავად).

შემოწმება, რომ დაცვა მუშაობს: სთხოვე Claude-ს, intent.md-ის სტატუსი accepted-ზე თავად შეცვალოს — უარს მიიღებ GUARD[G4]-ით, და ასეც უნდა იყოს. ძრავის ყველა შემოწმება ერთად (Windows-ზე — Git Bash-ში): bash .claude/hooks/py.sh tools/gates/gate.py (ბოლო ხაზი GATES PASS) და bash .claude/hooks/py.sh tools/gates/drill.py (~3 წუთი; DEAD/DEFECT=0 — ყოველი შემოწმება ცოცხალია).

ყოველდღიური მუშაობა

გახსენი ტერმინალი ან VS Code პროექტის საქაღალდეში და დაიწყე Claude — მან უკვე იცის, სად გაჩერდით. ჩვეულებრივად ესაუბრე. სტატუსის ზოლში 🧭-ით ჩანს, ხუთიდან რომელ ეტაპზეა პროექტი — განზრახვა, სპეციფიკაცია, არქიტექტურა, გეგმა და აშენება, ჩვენება — და რა არის შემდეგი ნაბიჯი, ხშირად ზუსტი ბრძანებით (მაგ. /approve spec 1). ეს ძრავის სამუშაო ციკლია (ADR-0001); ზოლი მხოლოდ დოკუმენტების სტატუსებს კითხულობს (ADR-0011). როცა ამთავრებ, თქვი „დავასრულოთ" (ან /session-close) — ის ჩაწერს, რა გაკეთდა, განაახლებს გეგმას და პროგრესს, გაუშვებს შემოწმებებს და შეინახავს. თუ სტატუსის ზოლში წითლად ანთია ↻3 ახალი სესია, ესე იგი საუბარი სამჯერ შეიკუმშა — დროა /session-close, მერე ახალი ტერმინალი ან /clear.

მოდელს სესიის დასაწყისში ირჩევ (/model) და შუაში აღარ ცვლი; ერთი თემა — ერთი სესია. რატომ — ქვემოთ, „ქეში და ხარჯი".

ბრძანებები

რა შეუძლია Claude-ს და რა არა

შეუძლია: ფაილების კითხვა და წერა, პროექტის შემოწმებების გაშვება, git-ში შენახვა ბრანჩზე (ბრანჩი — პროექტის ცალკე ასლი, რომელიც მთავარში შენი თანხმობით ერთიანდება). ეკითხება შენ: პროგრამების დაყენებას, ფაილების წაშლას, git push-ს და შერწყმას, თავად სამუშაო გარემოს (hook-ები, gate-ები, skill-ები, წესები, აგენტის ინსტრუქციები და გაკვეთილები) შეცვლას, ორკესტრაციის გაშვებას. არ შეუძლია: საიდუმლოების (.env) წაკითხვა, შემოწმებების გვერდის ავლა, ისტორიის გადაწერა, შენს მაგივრად დამტკიცება, სხვა სესიების ფაილების შეცვლა. გულწრფელად: ეს დაცვა „სიჩქარის ბორცვია" და არა სეიფის საკეტი — ამიტომ მის უკან მანქანური შემოწმებაც დგას და git-ის ისტორიაც. დეტალები — ADR-0004.

უსაფრთხოება და კონტროლი

გასაღებები. API გასაღებები და ტოკენები მხოლოდ .env ფაილში ჩაწერე. ის git-ში არ ხვდება, Claude კი მას ვერც კითხულობს და ვერც წერს. როგორ შექმნა, .env.example-ში წერია: დააკოპირე სახელით .env და PLACEHOLDER-ის ნაცვლად ნამდვილი მნიშვნელობა ჩასვი. გასაღები ჩატში არ ჩაწერო — ასეთი შეტყობინება Claude-მდე არ მივა და გაფრთხილებას მიიღებ.

sentinel (დარაჯი გამოტანაზე). თუ რომელიმე ბრძანების შედეგში გასაღები გამოჩნდა, Claude მას [REDACTED:…]-ად ხედავს. ფარული Unicode სიმბოლოები და გარე წყაროდან მოსული „ბრძანების მსგავსი" ტექსტი ინიშნება, რომ Claude-მა ის ბრძანებად არ მიიღოს.

sandbox (ბრძანებების იზოლაცია) და WSL2. Claude Code-ს შეუძლია ბრძანებები იზოლირებულად გაუშვას — ფაილებსა და ქსელზე წვდომა შეზღუდული აქვს, და ეს ერთადერთი ნამდვილი საზღვარია shell-ის მქონე აგენტზე (ნებართვების სიები ფანჯარაა, არა კედელი). ის მუშაობს macOS-ზე, Linux-სა და WSL2-ზე და ნაგულისხმევად გამორთულია; ბუნებრივ Windows-ზე საერთოდ არ არსებობს. სტატუსის ზოლი ყოველთვის გიჩვენებს, სად ხარ: 🛡 sandbox არ არის — Windows, გამორთულია ან ჩართულია. Windows-ზე იზოლაციისთვის Claude Code WSL2-ში გაუშვი (Ubuntu: wsl --install; პროექტი Linux-ის საკუთარ საქაღალდეში დააკლონე — /mnt/c-დან ნელია და ფაილის რეჟიმები ირევა); ჩართვა — sandbox.enabled: true ~/.claude/settings.json-ში ან პროექტის .claude/settings.json-ში (Linux-ზე bubblewrap და socat სჭირდება; ქსელის allowlist-ი ცარიელი იწყება და ყოველ ახალ ჰოსტზე ფანჯარა იხსნება). ნაკრები მას თავისით ჯერ არ რთავს — ჯერ ცოცხალი ცდაა საჭირო macOS-ზე ან Linux-ზე ([[ADR-0014-harness-hardening]]).

observatory (დაკვირვება). /observatory ქართულად გიჩვენებს, რა გააკეთეს აგენტებმა: რომელი ფაილები შეიცვალა, რომელი ბრძანება წერდა git-ში, აყენებდა, შლიდა ან ქსელში გადიოდა, რა უარყო guard-მა, რამდენი ტოკენი დაიხარჯა. /session-close ამის ერთ ხაზს სესიის ეპიზოდში ინახავს.

დავალებები. tasks/todo.md-ში Claude წერს, რას აკეთებს ახლა და რა მოდის შემდეგ, ხოლო „შენ გელოდება" ნაწილში — რა სჭირდება შენგან. მონიშნული დავალება მხოლოდ ქვითრით ითვლება (commit ან შენი სიტყვა).

გულწრფელად: shell-ის მქონე აგენტზე სრული გარანტია შეუძლებელია. მიღწევადია ფენები, რომლებიც შეცდომებს აჩერებს, და სრული კვალი, რომელიც გამოტოვებულსაც აჩენს. რა ვერ დავიცავით, ჩამოწერილია ADR-0007-ში.

ქეში და ხარჯი

Claude ყოველ ნაბიჯზე მთელ საუბარს თავიდან კითხულობს, იაფად კი მხოლოდ მაშინ, როცა მისი შენახული ასლი (prompt cache — ქეში) ჯერ ცოცხალია: მთავარ სესიაში ის დაახლოებით ერთ საათს ძლებს. სტატუსის ზოლის (statusline-ის) ბოლო ხაზი ამას გიჩვენებს — ♻ ქეში თბილია ~14:05-მდე, „იწურება", ან ❄ ცივია; ცივ და დიდ საუბარზე ისიც გეტყვის, რომ ახალი თემისთვის ახალი სესია იაფია. შენი საკუთარი სტატუსის ზოლი, თუ გაქვს, ადგილზე რჩება — ძრავა მას მხოლოდ ქეშის ხაზს უმატებს. რა დაჯდა სესია API-ის ფასით და რატომ აეწყო ასლი თავიდან, /observatory გიჩვენებს. დეტალები და ჩვევები — ADR-0010, process.md §5.

Obsidian — კონტექსტის გრაფი

1. გადმოწერე Obsidian (obsidian.md) და გახსენი: Open folder as vault → აირჩიე პროექტის საქაღალდე.
2. დააჭირე Ctrl+G (macOS-ზე Cmd+G; Graph view). ფერები: ნარინჯისფერი — განზრახვა, ლურჯი — ADR, მწვანე — სპეციფიკაციები, იისფერი — გეგმები, ოქროსფერი — დომენის ფაქტები, ნაცრისფერი — სესიები.
3. ნებისმიერ კვანძზე დაწკაპუნებით ფაილი იხსნება; ფაილის ზედა ნაწილში („Properties") ჩანს მისი სტატუსი და კავშირები.

ფაილის გადარქმევა Obsidian-ში უსაფრთხოა — ბმულები თავისით განახლდება.

საქაღალდეების რუკა

რა ჯერ არ არის

ძრავა მუშაობს, მაგრამ ზოგი ნაწილი ჯერ ჩართული არ არის — ეს გულწრფელად უნდა იცოდე. ბრძანებები სამივე სისტემაზე ერთი გამშვებით ეშვება (bash .claude/hooks/py.sh); Windows-სა და Linux-ზე ძრავა ხელით შემოწმდა, macOS-ზე — GitHub-ის ავტომატური შემოწმებით (CI), ნამდვილი სესიით კი ჯერ არა. ორკესტრაციის I ეტაპი (Sonnet წერს, Opus ამოწმებს) კოდში უკვე წერია (ADR-0005); მას დრილი ამოწმებს (tools/gates/drill.py, ჯგუფი orchestration), და შენი commit-ის შემოწმებაც მას უშვებს, როცა მისი რომელიმე ფაილი იცვლება. ის გამორთულია — ჩართვა შენი გადაწყვეტილებაა. დისპეჩერი (decision model, რომელიც მოდელს გვირჩევს) ჯერ მხოლოდ გადაწყვეტილებადაა ჩაწერილი (ADR-0009) და ამ შაბლონში კოდი არ აქვს. კოდის lint-ი, ტესტები და evals (კარიბჭეების 1–3 დონეები) ჩაირთვება მაშინ, როცა შენი პროექტის სტეკი (ტექნოლოგიები) გადაწყდება. ეს ყველაფერი შენს გადასაწყვეტად წინადადებებშიც წერია (memory/PROPOSALS.md).

ლიცენზია და წყაროები

MIT — იხილე LICENSE. შეგიძლია გამოიყენო, შეცვალო და გაავრცელო, თუ ლიცენზიის ტექსტს შეინარჩუნებ. სამი კრიტიკოსი (.claude/agents/critic-*.md) kimi-atlas-ის აგენტების მიხედვითაა ადაპტირებული (MIT), refuter — gentle-ai-ის review-refuter-ის მიხედვით (Apache-2.0); სხვა პროექტებიდან აღებული იდეები სახელით არის მოხსენიებული ADR-ებში, სადაც გამოიყენება.