مارکداون جاش تو پوشهٔ /src هست
هوش مصنوعیClaude Opus 5خلاصهٔ کاملتر
کارسون گراس، سازندهٔ htmx و مشاوری که با شرکتهای درگیر agentic coding (یعنی تولید کد با ایجنتهای LLM بهجای نوشتن دستی) کار میکنه، تو این مقاله میگه مارکداون دیگه مستندات نیست، خودش کد منبعه. نویسنده خودش نسبت به کد تولیدشده با هوش مصنوعی دودله، ولی میبینه سازمانها با سرعت دارن این مسیر رو میرن.
به گفتهٔ نویسنده، خیلیها LLM رو مثل کامپایلر میبینن که مشخصات سطح بالا رو به کد تبدیل میکنه. اون این تشبیه رو کامل قبول نداره و یه دلیلش اینه که کامپایلر کد منبعش رو نگه میداره ولی LLM نه. کد معمولاً از یه سری پرامپت موقت تو یه جلسهٔ کار با ایجنت درمیاد و بعد اون پرامپتها گم میشن. یعنی تنها «حقیقت» باقیمونده خود کد تولیدشدهست و دلیل تصمیمها یه جای دیگه، مثلاً تو Linear یا Slack یا ویکی، پخش شده.
پیشنهاد نویسنده اینه که بخشی از فایلهای مارکداونی که الان موقت نگه میداریم، مثل specها و planها و AGENTS.md، به یه پوشهٔ جدید کنار کد یعنی /src/md منتقل بشن. مارکداون متن سادهست، پس diff و grep و بررسی تو pull request روش جواب میده؛ LLMها راحت میخونن و مینویسنش و آدمها هم بدون ابزار خاص ویرایشش میکنن. محتوای این پوشه از سند طراحی معمولی پایینتره: تصمیمهای معماری، تصمیمهای سطح کد و طراحی داده.
نویسنده که طرفدار اصل locality (یعنی اینکه توضیح هر چیز باید نزدیک خودش باشه) هست، میگه اینجوری هر ماژول نیت خودش رو کنار خودش داره و ایجنتها لازم نیست برای فهم کد جای دیگهای رو بگردن. به نظرش تستها برای تعامل آدم و ایجنت مناسب نیستن چون تشریفات زیادی دارن و زیادی سطح پایینن. تقسیم کار پیشنهادیش اینه که مارکداون تو /src نقش تقریباً مشخصات رو داشته باشه و تستها از روی اون ساخته بشن.
نویسنده تأکید میکنه این پوشه باید بیشتر دست آدمها نوشته و مرتب بشه، نه ایجنتها، و مثل کد «بودجهٔ پیچیدگی» داره. وقتی توسعهدهنده کد تولیدشده رو دستی سادهتر یا محدودتر میکنه، باید اون تغییر رو به مارکداون هم برگردونه. ساختاری که برای شروع پیشنهاد داده این شکلیه:
src/
md/
README.md # index of all md, entry point for agents
TODO.md # a list of general TODOs open for this module
OVERVIEW.md # a technical overview of this module
features/FEATURE_1.md # a set of feature-specific documents
data/DATAMODEL_1.md # descriptions of data models in the moduleخودش قبول داره این بخش هنوز خامه و بیشتر دعوت به بحثه. پوشههایی مثل features و data و api و infrastructure اختیاریان و فقط برای تقسیم توضیح رفتار ماژول از زاویههای مختلف هستن.
نکات کلیدی:
- نویسنده، کارسون گراس، سازندهٔ htmx و استاد دانشگاه Montana State هست.
- پیشنهاد اصلی: ذخیرهٔ مارکداون نیت کد تو پوشهٔ /src/md کنار خود کد.
- کد و تست باید از این مارکداون ساخته بشن، نه از پرامپتهای موقت.
- فایل README.md تو این پوشه نقطهٔ ورود ایجنتها و فهرست بقیهٔ فایلهاست.
- نویسنده معتقده این پوشه باید بیشتر دست آدم نوشته بشه و LLMها کامپایلر نیستن.
