CLAUDE.md மற்றும் AGENTS.md: அவை என்ன, அவற்றில் என்ன எழுத வேண்டும், முகவர் விதிகளைப் புறக்கணிப்பது ஏன்

CLAUDE.md மற்றும் AGENTS.md என்றால் என்ன

இரண்டும் களஞ்சியத்தின் மூலத்தில் உள்ள சாதாரண Markdown கோப்புகள். அமர்வின் தொடக்கத்தில் முகவர் அவற்றைத் தானாக சூழலில் ஏற்றுகிறது. இவற்றின் மூலம் குறியீட்டிலிருந்து முகவரால் தானாக அறிய முடியாதவற்றைச் சொல்கிறீர்கள்: சூழலை எப்படித் தொடங்குவது, வேலையைச் சரிபார்க்க எந்தக் கட்டளைகள், எந்தத் திட்ட விதிகள் விவாதத்துக்குரியவை அல்ல, விரிவான ஆவணங்கள் எங்கே உள்ளன.

CLAUDE.md என்பது Claude Code படிக்கும் கோப்பு. AGENTS.md என்பது அதே கருத்தைக் கொண்ட திறந்த வடிவம், பல coding முகவர்களால் ஆதரிக்கப்படுகிறது. குழுவில் பல முகவர்கள் பயன்பட்டால், முக்கிய உள்ளடக்கத்தை AGENTS.md-இல் வைத்து CLAUDE.md-இலிருந்து அதற்குக் குறிப்பிடுவது வசதி. Claude Code @ குறியுடன் மற்றொரு கோப்பை இறக்குமதி செய்ய ஆதரிக்கிறது:

# CLAUDE.md
@AGENTS.md

இவ்வாறு விதிகள் ஒரே இடத்தில் வாழ்கின்றன, இரு கோப்புகளுக்கிடையே முரண்பாடு ஏற்படாது.

முகவர் இந்தக் கோப்புகளை எப்படிப் படிக்கிறது

வழிகாட்டல் கோப்பின் உள்ளடக்கம் system prompt உடன் மாதிரியின் சூழல் சாளரத்தில் சேர்ந்து, அமர்வு முழுவதும் அங்கேயே இருக்கும். அதிலிருந்து மூன்று முக்கிய விளைவுகள்.

• ஒவ்வொரு வரியும் சூழலில் இடம் பிடிக்கிறது. ஒவ்வொரு தொடக்கத்திலும் கோப்பு முழுவதும் படிக்கப்படுகிறது, தற்போதைய பணிக்கு அதன் பத்தில் ஒரு பகுதி மட்டுமே தேவைப்பட்டாலும்.
• இவை இயக்கப்படும் விதிகள் அல்ல, உரை. மாதிரி இவற்றை மற்ற சூழலுடன் சேர்த்துக் கருதுகிறது, நூறு சதவீதம் கடைப்பிடிப்பதற்கு உத்தரவாதம் இல்லை. கடுமையான தடைகளை இயந்திர வழிமுறைகளால் ஆதரிக்க வேண்டும்: சரிபார்ப்புகள், hooks, அணுகல் கட்டுப்பாடுகள்.
• கோப்புகளை அடுக்கலாம். Claude Code திட்ட மூலத்திலிருந்தும் ~/.claude/ பயனர் கோப்புறையிலிருந்தும் CLAUDE.md-ஐ ஏற்றுகிறது, துணைக் கோப்புறைகளில் உள்ள கோப்புகள் முகவர் அந்தக் கோப்புறைகளின் கோப்புகளுடன் வேலை செய்யும்போது ஏற்றப்படுகின்றன. இதனால் தொகுதியின் விதிகளை அந்தத் தொகுதிக்கு அருகே வைக்கலாம்.

CLAUDE.md மற்றும் AGENTS.md-இல் என்ன எழுத வேண்டும்

நல்ல வழிகாட்டல் கோப்பு ஒரு வரைபடம், பாடநூல் அல்ல. முதல் நாளில் ஒரு மூத்த சக ஊழியரிடம் முகவர் கேட்கக்கூடிய கேள்விகளுக்குப் பதிலளிக்கிறது.

1. திட்டத்தை எவ்வாறு உருவாக்கிச் சரிபார்ப்பது

மிக மதிப்புமிக்க பகுதி. «முடிந்தது» என்று சொல்வதற்கு முன் முகவர் கட்டாயம் இயக்க வேண்டிய குறிப்பிட்ட கட்டளைகள்: tests, linter, type check, சூழலைத் தொடங்குதல். இவை இல்லாவிட்டால் முகவர் தன்னை «கண்ணால் பார்த்து» சரிபார்க்கிறது.

2. கடுமையான வரம்புகள்

எந்த நிலையிலும் மீறக்கூடாத விஷயங்களின் சிறிய பட்டியல்: பாதுகாப்பு மற்றும் தரவின் மாறாத நியதிகள். இவற்றை மாறாத நியதிகளாக எழுதுங்கள், செயலாக்க அறிவுறுத்தல்களாக அல்ல: «எல்லா SQL வினவல்களும் parameterized», «இந்தக் கோப்பில் இந்தச் செயல்பாட்டைப் பயன்படுத்து» அல்ல.

3. திட்ட வரைபடம்

எது எங்கே உள்ளது: கோப்புறை அமைப்பு பற்றிய சில வரிகள், விவரங்கள் எங்கே தேடுவது. ஒவ்வொரு பெரிய தலைப்புக்கும் தனி ஆவணத்துக்கான இணைப்பு உள்ளது, அதை முகவர் அந்தத் தலைப்பில் வேலை செய்யும்போது மட்டுமே திறப்பான்.

4. வேலையின் நிலை எங்கே உள்ளது

முந்தைய அமர்வு நின்ற இடத்திலிருந்து தொடர எங்கே பார்க்க வேண்டும்: திட்டக் கோப்பு, முன்னேற்றப் பதிவு அல்லது backlog. இது அமர்வுகளுக்கு இடையே முகவரின் «மறதியை» சரிசெய்கிறது.

எதை எழுதக் கூடாது

• குறியீட்டிலிருந்து முகவர் அறியக்கூடியவை. சார்புகளின் பட்டியல் package.json அல்லது pyproject.toml-இல் உள்ளது, வகுப்புகளின் அமைப்பு குறியீட்டிலேயே உள்ளது.
• பொதுவான அறிவுரைகள். «சுத்தமான குறியீடு எழுது» அல்லது «கவனமாக இரு» நடத்தையை மாற்றாது, இடத்தை மட்டும் பிடிக்கிறது.
• திட்ட வரலாறு மற்றும் ஒருமுறைக் குறிப்புகள். «மார்ச்சில் MySQL 5.7-இலிருந்து மாறினோம்» தற்போதைய பணிக்கு உதவாது.
• அரிதான பணிகளுக்கான விரிவான வழிமுறைகள். Deploy அல்லது தரவு migration நடைமுறை வாரத்துக்கு ஒரு முறை தேவைப்படும் — தனி ஆவணம் அல்லது skill-இல் வையுங்கள்.
• ரகசியங்கள். கோப்பு களஞ்சியத்தில் இருக்கும், முழுவதும் மாதிரிக்குச் செல்லும். Tokens மற்றும் கடவுச்சொற்கள் சூழல் மாறிகளில் மட்டுமே இருக்க வேண்டும்.

கோப்பில் எழுதிய விதியை முகவர் ஏன் புறக்கணிக்கிறது

பழக்கமான கதை: முகவர் தவறு செய்தான் — கோப்பில் ஒரு விதி சேர்க்கப்பட்டது. மீண்டும் தவறு, இன்னொரு விதி. சில மாதங்களில் கோப்பில் நூற்றுக்கணக்கான வரிகள், முக்கியமான பாதுகாப்பு விதியை முகவர் அது இல்லாததுபோல மீறுகிறான். பொதுவாக நான்கு காரணங்கள் ஒரே நேரத்தில் செயல்படுகின்றன.

வீங்கிய கோப்பு

600 வரிக் கோப்பு தோராயமாக 10–20 ஆயிரம் tokens. சூழல் சாளரம் பெரிதாகத் தோன்றும், ஆனால் அது குறியீடு, கட்டளை வெளியீடுகள் மற்றும் உரையாடல் வரலாற்றுக்கிடையே பகிரப்படுகிறது. வழிகாட்டல் அதிக இடம் பிடித்தால், ஒவ்வொரு விதியும் குறைவான கவனத்தைப் பெறுகிறது, பணிக்கான இடம் குறைகிறது.

நடுவில் உள்ள விதி

மொழி மாதிரிகள் நீண்ட உரையின் நடுவில் உள்ள தகவலை அதன் தொடக்கம் மற்றும் முடிவில் உள்ளதை விட மிகக் குறைவாகவே பயன்படுத்துகின்றன. 600 வரிகளில் 300-ஆவது வரி உள்ள விதி மிகவும் பலவீனமான இடத்தில் உள்ளது.

முன்னுரிமை இல்லை

விவாதிக்கக்கூடாத தடையும், ஒரு கணநேர நடைக் குறிப்பும் ஒரே மாதிரி, பட்டியலில் ஒரு வரியாக எழுதப்படுகின்றன. எது முக்கியம் என்று முகவருக்குத் தெரியாது. மூன்று முரண்பட்ட நடை விதிகள் இருந்தால், நடத்தை ஓட்டத்துக்கு ஓட்டம் தாறுமாறாகிறது.

அழுகல்

விதியைச் சேர்ப்பது இலவசம், ஆனால் நீக்குவது பயமுறுத்துகிறது: «அதை நம்பி எதுவும் இருக்கலாம்». எனவே கோப்பு தொடர்ந்து வளர்கிறது, பயனுள்ள வரிகளின் விகிதம் குறைகிறது. இதை சமிக்ஞை-இரைச்சல் விகிதத்தால் அளவிடலாம்: ஒரு வழக்கமான பணிக்கு உண்மையில் எத்தனை வரிகள் தேவை, எத்தனை தேவையில்லை.

சரிசெய்வது எப்படி: சுவர் உரைக்கு பதிலாக ரௌட்டர்

ஒரு காரணத்தை மட்டும் சரிசெய்வது பயனற்றது: கோப்பைச் சுருக்கினாலும் கட்டமைப்பு இல்லாவிட்டால் விதிகள் இன்னும் கலந்தே இருக்கும். பல நடவடிக்கைகளின் கூட்டு வேலை செய்கிறது.

1. நுழைவுக் கோப்பை ரௌட்டராக்குங்கள். 50–150 வரிகள்: சரிபார்ப்புக் கட்டளைகள், கடுமையான வரம்புகள், திட்ட வரைபடம், தலைப்புவாரி ஆவணங்களுக்கான இணைப்புகள்.
2. தலைப்புகளைத் தனிக் கோப்புகளுக்கு நகர்த்துங்கள். உதாரணமாக docs/agents/deploy.md, docs/agents/database.md. தேவைப்படும்போது முகவர் அவற்றைத் திறக்கும். Claude Code-இல் மீண்டும் வரும் நடைமுறைகளுக்கு skills பொருத்தமானவை, அவை தேவைப்படும்போது மட்டுமே ஏற்றப்படுகின்றன.
3. முக்கியமானதை மேலே உயர்த்துங்கள். கடுமையான வரம்புகளைக் கோப்பின் தொடக்கத்தில், MUST குறியுடன் ஒரு சிறிய தனிப் பகுதியாக வையுங்கள்.
4. முரண்பாடுகளை நீக்குங்கள். ஒவ்வொரு தலைப்புக்கும் ஒரு விதி. விதிவிலக்கு இருந்தால் அதை விதிக்கு அருகே எழுதுங்கள்.
5. விதியை இயந்திர வழிமுறையால் ஆதரியுங்கள். மீறல் நடக்கவே கூடாது என்றால், உரை மட்டும் போதாது. அதைப் பிடிக்கும் சரிபார்ப்பு தேவை: linter, test, pre-commit hook அல்லது முகவர் hook, அல்லது அணுகல் கட்டுப்பாடு.
6. வழக்கமாக மறுஆய்வு செய்யுங்கள். வரி வரம்பை நிர்ணயித்து, ஒவ்வொரு சேர்ப்பின் போதும் எதை நீக்கலாம் அல்லது நகர்த்தலாம் என்று கேளுங்கள்.

விதியா அல்லது சரிபார்ப்பா?

சுருக்கப்பட்ட AGENTS.md எடுத்துக்காட்டு

# AGENTS.md — payment backend (FastAPI, PostgreSQL)

## MUST — மீறக் கூடாதவை
- பணத் தொகை பைசாவில் int, ஒருபோதும் float அல்ல
- parameterized SQL மட்டும், f-string அல்ல
- பயன்படுத்திய migration-ஐ மாற்றக் கூடாது, புதிய migration மட்டும் சேர்க்கவும்
- ரகசியங்கள் சூழல் மாறிகளிலிருந்து மட்டும்

## «முடிந்தது» என்பதற்கு முன் சரிபார்ப்பு
docker compose up -d     # சூழல்
make lint                # ruff + mypy
make test                # pytest
make e2e                 # checkout காட்சி
Unit tests பச்சையாக இருந்தாலும் e2e இல்லையென்றால் அது «முடிந்தது» அல்ல.

## வரைபடம்
- app/payments/   — தொகைக் கணக்கீடு, தள்ளுபடி, வழங்குநர் webhook
- app/api/        — HTTP endpoints
- tests/e2e/      — பயனர் காட்சிகள்
விவரங்கள்: docs/agents/architecture.md, docs/agents/database.md

## வேலையின் நிலை
- PLAN.md      — தற்போதைய இலக்கு, முடிவு அளவுகோல்கள், அடுத்த படி
- PROGRESS.md  — செய்தவை மற்றும் அவை எப்படி சரிபார்க்கப்பட்டன, முட்டுச்சந்துகள்
- BACKLOG.md   — வழியில் கண்ட விஷயங்கள்: இங்கே எழுதுங்கள், இப்போது சரி செய்யாதீர்கள்

அமர்வின் முடிவில் PROGRESS.md மற்றும் PLAN.md-இல் அடுத்த படியைப் புதுப்பிக்கவும்.

இங்கு இல்லாதவற்றைக் கவனியுங்கள்: நூலக பட்டியல், நடை அறிவுரைகள், திட்ட வரலாறு. அவை எல்லாம் குறியீட்டிலிருந்து தெரிகின்றன, சரிபார்ப்புகளால் பூட்டப்பட்டுள்ளன, அல்லது தலைப்புவாரி ஆவணங்களில் உள்ளன.

அமர்வுகளுக்கு இடையே மறதி: வழிகாட்டல் கோப்பும் திட்டக் கோப்பும்

வழிகாட்டல் கோப்பு திட்டத்தில் எப்படி வேலை செய்வது என்று விவரிக்கிறது, ஆனால் இப்போது என்ன நடக்கிறது என்று அல்ல. அதற்கு முகவர் தொடக்கத்தில் படித்து அமர்வின் முடிவில் புதுப்பிக்கும் தனி நிலைக் கோப்பு தேவை. அதில் இருக்க வேண்டியவை: இலக்கு, செய்தவை மற்றும் அவை சரிபார்க்கப்பட்ட விதம், காரணங்களுடன் முடிவுகள், நிராகரித்த வழிகள், அடுத்த படிக்கான ஒரு வாக்கியம். தரத்தைச் சோதிப்பது எளியது: புதிய அமர்வைத் திறந்து «தொடர்» என்று எழுதுங்கள், கேள்விகள் கேட்காமல் முகவர் பயனுள்ள வேலையைத் தொடங்குகிறானா என்று பாருங்கள்.

இரண்டு கோப்புகளைக் கலக்காதீர்கள். வழிகாட்டல் அரிதாக மாறுகிறது, எல்லா வேலைகளுக்கும் பொருந்தும். திட்டம் ஒவ்வொரு அமர்வும் மாறுகிறது, தற்போதைய வேலைக்கு மட்டும் பொருந்தும். கலந்தால் வழிகாட்டல் கோப்பு விரைவில் காலாவதியான குறிப்புகளால் நிரம்பிவிடும்.

கோப்பு வேலை செய்கிறதா என்று சரிபார்ப்பது எப்படி

வழிகாட்டல் கோப்பையும் சரிபார்க்க வேண்டும். சில வழக்கமான பணிகளை எடுங்கள் — பிழை திருத்தம், சிறிய அம்சம், மறுஆக்கம் — குறிப்புகள் இல்லாமல் முகவர் என்ன செய்கிறான் என்று பாருங்கள்: சரியான கட்டளைகளை இயக்குகிறானா, சரியான தலைப்புவாரி ஆவணத்தைத் திறக்கிறானா, கடுமையான வரம்புகளைக் கடைப்பிடிக்கிறானா. ஒரு விதி மீறப்பட்டால் முதலில் கேளுங்கள்: அது தெரிகிறதா, அதற்கு முரண்பாடு உள்ளதா, தானியங்கிச் சரிபார்ப்பால் அதை மாற்ற முடியுமா. புதிய வரி சேர்ப்பது கடைசி வழி.

சுருக்கம்

CLAUDE.md மற்றும் AGENTS.md முகவர் திட்டத்துக்குள் நுழையும் வாசல். சுருக்கமான வரைபடமாக இருக்கும்போதுதான் அவை வேலை செய்கின்றன: சரிபார்ப்புக் கட்டளைகள், மேலே கடுமையான வரம்புகள், விவரங்கள் மற்றும் திட்டக் கோப்புக்கான இணைப்புகள். ஒரு விதி புறக்கணிக்கப்பட்டால், காரணம் கிட்டத்தட்ட எப்போதும் வீங்கிய, கட்டமைப்பற்ற கோப்புதான்; உண்மையில் முக்கியமான விதிகளைச் சரிபார்ப்புகளும் hooks-உம் ஆதரிக்க வேண்டும். முகவரின் வழிகாட்டலையும் நிலையையும் எப்படி ஒழுங்கமைப்பது என்பது harness engineering பாடநெறியில் நடைமுறையில் கற்பிக்கப்படுகிறது.