В края на тази глава имаш точно толкова структура, че да не се изгубиш в истински проект: какво е repo, file tree и module, защо е важна подредбата за лесна проверка и как една карта на проекта кара Claude да работи много по-добре.
AVATAR OPENER · ~90s
Гледай: даваме карта на истински проект и виждаме как работата на Claude се променя заради нея
HeyGen avatar · generated, consistent presenter
Вече имаш терминал, от който не те е страх, и companion repo на машината ти. Тази глава ти дава нагласата да се движиш из истински проект, без да се чувстваш изгубен. Това не е курс по компютърни науки, а шепа структурни идеи, които позволяват на човек, който не пише код, уверено да управлява създаването на нещо истинско. Нищо повече.
Обещанието е нарочно скромно: достатъчно архитектура, за да не се изгубиш, а не диплома. Няма да учиш алгоритми или структури от данни. Ще научиш какво всъщност означават думите repo, file tree и module, един принцип за това как да подреждаш нещата и защо всичко това прави Claude видимо по-добър, когато го управляваш. Тази последна част е истинската награда, така че я дръж под око. Структурата не е подреденост заради самата подреденост, тя е това, което позволява и на теб, и на модела да осмисляте един проект, без да държите всичко наведнъж в главата си.
Структурата не е просто да ти е подредено. Тя е за това да направиш проекта лесен за проверка.
Купчината е нещо, в което ровиш. Структурата е нещо, което можеш да осмислиш логически. Разликата е изцяло в това дали е организирано така, че да се проверява лесно.
ТРИ ДУМИ, КОИТО ОТКЛЮЧВАТ ВСИЧКО ОСТАНАЛО
Почти целият страх в тази сфера идва от три думи, които хората подхвърлят небрежно, забравили, че някога и те самите не са ги знаели. Ето ги, обяснени просто.
Repo
Кратко от repository. Това е просто папката на проекта, онова единствено място, което съдържа всичко за него: файловете, историята, правилата. Companion repo-то, което клонира по-рано, е точно това.
File tree
Подредбата на папките в един проект, нарисувана. Същото влагане на папка в папка, което виждаш във всеки прозорец с файлове, само че изписано като списък, който хващаш с един поглед.
Module
Едно самостоятелно парче от проекта, което върши една конкретна работа. Чекмедже с ясен етикет. Можеш да го разбереш и да го провериш, без да отваряш всяко друго чекмедже.
Convention
Договорен начин за правене на нещата в този проект: къде отиват файловете, как се казват, какви са правилата. Написано веднъж и спазвано всеки път, както от теб, така и от Claude.
Това е речникът. Repo е папката на проекта. File tree е неговата форма. Module е едно чекмедже с етикет, което върши една работа. Convention е домашното правило за това как са подредени чекмеджетата. Само с тези четири думи можеш да говориш за структурата на всеки проект и да схващаш какво имат предвид хората, когато ги ползват около теб.
ДЪЛБОКИ ЧЕКМЕДЖЕТА, А НЕ МНОГО ПЛИТКИ
Има един принцип на дизайна, който си струва да запомниш. Идва от софтуерното мислене, обяснено просто от Matt Pocock, а корените му стигат до компютърния учен John Ousterhout. Става дума за това как да разделиш един проект на модули, на онези чекмеджета с етикети. Добрият начин са дълбоките модули: малък брой чекмеджета, като всяко върши сериозна работа зад един прост етикет. Лошият начин са плитките модули: много малки чекмеджета, всяко от които почти нищо не прави, така че се налага да отвориш двайсет от тях, за да проследиш една-единствена нишка.
Много плитки чекмеджета
Всичко е разделено на малки парченца, които почти нищо не правят. За да проследиш една идея, отваряш дузина файлове и ги държиш всичките в главата си. Никой не може да го провери лесно, включително и Claude.
Резултат: технически организирано, но всъщност е лабиринт.
VS
Малко дълбоки чекмеджета
Малък брой модули, като всеки върши истинска и цялостна работа зад ясен етикет. Можеш да отвориш един, да го разбереш напълно и да го провериш, без да пипаш останалите.
Резултат: лесно за осмисляне, лесно за проверка, лесно за поправяне.
Защо да те е грижа за това, щом не пишеш код, а управляваш Claude? Защото моделът работи по същия начин като теб. Когато един проект се състои от няколко дълбоки и ясно обозначени модула, Claude намира това, което му трябва, променя едно нещо, без да счупи три други, и проверява собствената си работа. Когато проектът е хаос от плитки фрагменти, моделът губи нишката точно както би станало и с теб, а грешките му се умножават. Организирането за лесна проверка не е услуга за бъдещите програмисти. То е нещото, което прави Claude надежден за проекта ти още днес.
ФАЙЛЪТ С НАЙ-ГОЛЯМА ТЕЖЕСТ: КАРТАТА НА ПРОЕКТА
Ето най-полезното структурно нещо, което можеш да направиш, и то изобщо не изисква писане на код. Даваш на проекта карта: един кратък файл, който стои в папката му и казва на всеки AI, който работи там, какво представлява този проект, как е организиран и какви правила трябва да спазва. В Claude Code този файл има конкретно име и се чете автоматично в началото на всяка сесия, така че Claude пристига вече ориентиран, вместо да налучква.
Без карта Claude започва на чисто всеки път, проучва отново и прави предположения, които може да не съвпадат с начина, по който реално работиш. С нея той отваря проекта, като вече знае структурата и правилата, точно както би направил един добър нов служител, след като прочете инструкциите за новодошли. Това е същата идея като личната конституция от курса за начинаещи, но насочена към един-единствен проект, а не към теб.
Напиши карта на проекта (идеята зад CLAUDE.md)
Помогни ми да напиша кратка карта на проекта за [моя проект], файлът, който Claude
трябва да прочете първи, когато работи тук.
Интервюирай ме накратко, след което го напиши с тези части, като го държиш стегнато:
- Какво е този проект в две прости изречения.
- Как е организиран: главните папки и за какво е всяка от тях.
- Правилата: как се кръщават нещата, къде отиват новите файлове,
онези правила, които този проект винаги спазва.
- Никога: нещата, които Claude не трябва да прави в този проект.
- Когато не си сигурен: задай ми един ясен въпрос, преди да гадаеш.
Направи го достатъчно кратко, така че четенето му да отнема под минута. Карта, а не ръководство.
Преди: всяка сесия обясняваш наново къде стои какво и какви са
правилата ти, а Claude пак греши в половината случаи.
След: Claude отваря проекта, като вече знае подредбата, следва
именуването ти, без да му се казва, и пита, вместо да предполага, когато
се сблъска с нещо, което картата не покрива.
Една честна бележка за това как да създадеш картата, заета от хората, които са измислили тази функция: не прекалявай с нея и не я усложнявай предварително. Започни без карта, поработи малко по проекта и забележи къде постоянно поправяш Claude. Тези поправки са самата карта, тя се пише сама. После просто ги запиши. Карта, родена от истинска работа и истински поправки, е много по-добра от дълга теоретична, съчинена още първия ден.
NOW YOU TRY · СЪЗДАЙ
Дай карта на един истински проект
Вземи един истински проект, companion repo-то, папка с твоя собствена работа или каквото и да е, в което има повече от няколко файла. Използвай промпта по-горе, за да напишеш неговата карта на проекта. Опиши конкретно правилата, които реално спазваш, и бъди честен за нещата, които Claude никога не трябва да прави тук. Направи я така, че да се чете за под минута. После, ако можеш, сложи я в папката на проекта и започни нова сесия, за да усетиш разликата.
Right if картата би позволила на способен непознат или на нова сесия с Claude да разбере проекта ти и неговите правила с едно кратко четене, без да обясняваш нищо на глас.
Show the worked solution
Упражнението работи, когато картата замени разговор, който ти е омръзнало да водиш. Да кажем, че проектът е малък сайт, който поддържаш. Без карта всеки път, когато вкараш Claude в него, обясняваш едни и същи неща: страниците живеят тук, стиловете са там, никога не ползваме тази библиотека, винаги пишем текстовете в този тон. Напиши картата и това ще станат четири реда, които Claude чете автоматично. Частта "какво е това" дава описание в две изречения, за да знае той каква е целта. Подредбата посочва двете или трите истински папки и какво съдържа всяка от тях, за да спре да гадае къде отива нов файл. Правилата хващат реалните ти изисквания: модела на именуване, тона на говорене, онази библиотека, която отказваш да ползваш. Списъкът с неща, които никога не трябва да се правят, улавя конкретните грешки, които си го виждал да прави: не пипай конфигурацията, не си измисляй текстове, не добавяй зависимости, без да попиташ. Сега една нова сесия отваря проекта и вече е ориентирана, а разликата е мигновена: по-малко грешни предположения, по-малко повторни обяснения, а когато се сблъска с нещо, което картата не покрива, той пита, вместо да гадае. Причината това да е структурният ход с най-голяма тежест е, че ти струва един кратък файл, а се отплаща при всяка следваща сесия, което е точно онова натрупване, което искаш от всичко, което създаваш веднъж.
WATCH FOR
✗Разделяш проекта на много малки парченца, за да изглеждаш организиран. Плитките модули създават лабиринт. Предпочитай няколко дълбоки и ясно обозначени чекмеджета, като всяко върши цялата работа и може да бъде проверено самостоятелно.
✗Пропускаш картата на проекта и обясняваш наново при всяка сесия. Една карта за минута четене, която се зарежда автоматично, е много по-добра от това да ориентираш Claude ръчно всеки път. Напиши я веднъж, ползвай я винаги.
✗Пишеш огромна теоретична карта още първия ден. Прекалено усложняване. Започни без карта, следи къде постоянно поправяш Claude и изгради картата точно от тези истински поправки.
✗Организираш, за да изглежда добре, а не за да се проверява лесно. Тестът за добра структура е дали едно парче може да се разбере и провери, без да се отварят останалите. Оптимизирай за това.
WHAT YOU LEARNED
The takeaways
Речникът е малък: repo е папката на проекта, file tree е неговата форма, module е едно чекмедже с етикет, което върши една работа, convention е домашното правило.
Предпочитай малко дълбоки модули пред много плитки. Да организираш нещата така, че всяко парче да може да се провери само по себе си, е целият смисъл на структурата.
Структурата помага на Claude по същата причина, поради която помага и на теб: той може да намира неща, да променя една част безопасно и да проверява работата си, когато проектът не е просто разхвърлян хаос.
Ходът с най-голяма тежест е кратка карта на проекта, която се чете автоматично и казва на Claude какво е този проект, как е подреден и какви са правилата му.
Изгради картата от реалната работа: започни без нея, запиши поправките, които постоянно правиш, и я запази достатъчно кратка, за да се чете за под минута.
Your project · направи карта на проекта си
Дай на проекта си една истинска карта тази седмица и усети как новата сесия пристига вече ориентирана. Вече имаш достатъчно структура, за да управляваш истинско създаване, без да се изгубиш. Следващата глава превръща еднократното изпълнение в система: /goal като полярната звезда, която заключваш, и /loop, който кара една задача да се движи сама.
Не ти трябва диплома по компютърни науки, за да управляваш истински софтуер. Трябват ти четири думи, един принцип и карта от една страница. Дай на проекта форма, която е лесна за проверка, и така и ти, и Claude ще спрете да се губите в него.