seiso দিয়ে AI-লিখিত প্রকল্পের ডকুমেন্টেশন লিন্ট করুন

seiso কী করে

seiso হলো AI দিয়ে লেখা এবং মানুষ ও কোডিং এজেন্টদের পড়ার জন্য তৈরি প্রকল্পের ডকুমেন্টেশনের একটি Markdown কনভেনশন ও লিন্টার। এটি রিপোজিটরির ডকুমেন্টেশনকে সামঞ্জস্যপূর্ণ, রক্ষণাবেক্ষণযোগ্য এবং ভবিষ্যৎ পরিবর্তনের প্রেক্ষাপট হিসেবে ব্যবহারযোগ্য রাখতে সহায়তা করে।

প্রতিটি প্রকল্পকে নিজস্ব ডকুমেন্টেশন নিয়ম তৈরি করতে বাধ্য করার বদলে, টুলটি একটি অভিন্ন কনভেনশনের বিপরীতে ডকুমেন্ট পরীক্ষা করে। প্রতিটি ডকুমেন্টে howto, reference বা adr-এর মতো একটি ধরন ঘোষণা করা হয় এবং সেই ধরনের জন্য উপযুক্ত উপাদানই রাখা হয়।

seiso প্রতিটি তথ্যের জন্য একটি নির্ভরযোগ্য মূল স্থান রাখতেও উৎসাহ দেয়। একই তথ্য পুনরাবৃত্তি না করে অন্যান্য পৃষ্ঠার সেই উৎসের সঙ্গে লিংক করা উচিত। এতে অসামঞ্জস্য কমে, বিশেষ করে যখন AI-নির্মিত ডকুমেন্টেশন একাধিক ফাইলে কোনো ফিল্ডের তালিকা, সংস্করণ, অবস্থা বা সংখ্যা কপি করে।

ডকুমেন্টেশনের মূল নীতিমালা

• প্রতিটি ডকুমেন্টে একটি ধরন ঘোষণা করতে হবে এবং সেই ধরনের উদ্দেশ্য অনুসরণ করতে হবে। একটি how-to ধাপ ব্যাখ্যা করে, আর নকশার যুক্তি ADR-এ থাকা উচিত।
• প্রতিটি তথ্যের একটি মূল স্থান থাকবে। পুনরায় উল্লেখ না করে অন্যান্য ডকুমেন্টে সেই নির্ভরযোগ্য পৃষ্ঠার লিংক দিতে হবে।
• দীর্ঘদিন ব্যবহৃত পৃষ্ঠায় এমন মান এড়িয়ে চলতে হবে যেগুলো পৃষ্ঠাটির চেয়ে দ্রুত বদলে যায়, যেমন সংস্করণ, ডিপ্লয়মেন্টের অবস্থা এবং সংখ্যা।
• কোনো বাক্যে নির্দিষ্ট বাস্তবায়ন-সংক্রান্ত তথ্যের উল্লেখ থাকলে একটি পয়েন্টার সেই ফাইল বা প্রতীক শনাক্ত করে।
• সম্পূর্ণ ডকুমেন্টেশনে যিনি অনুরোধ করেছেন তাকে সম্বোধন করা বা ডকুমেন্ট কীভাবে তৈরি হয়েছে তা বর্ণনা করা উচিত নয়।
• কোনো টুল যে সিদ্ধান্ত নিতে পারে না, সেই বিচারভিত্তিক সিদ্ধান্তের কারণ নথিভুক্ত করতে হবে। কারণহীন ব্যতিক্রম নিজেই একটি লঙ্ঘন।

seiso এই ডকুমেন্টেশন নিয়মগুলোর ওপর গুরুত্ব দেয়। গদ্যটি মেশিনে লেখা বলে মনে হয় কি না তা নির্ধারণের চেষ্টা করে না এবং ফরম্যাটিং ও বানান অন্য টুলের ওপর ছেড়ে দেয়।

seiso ইনস্টল করুন

সমর্থিত ইনস্টলেশন পদ্ধতিগুলোর যেকোনো একটি বেছে নিন। Rust, Python এবং npm প্যাকেজে একই কমান্ড-লাইন টুল দেওয়া হয়।

cargo install seiso

uv tool install seiso
# অথবা pipx ব্যবহার করুন:
pipx install seiso

npm install -g @scarletkc/seiso

PyPI এবং npm প্যাকেজে Apple silicon ও Intel-ভিত্তিক macOS, glibc-সহ Linux x64 ও arm64 এবং Windows x64-এর জন্য আগে থেকে তৈরি বাইনারি রয়েছে। Alpine-এর মতো musl-ভিত্তিক Linux ডিস্ট্রিবিউশনসহ অন্যান্য প্ল্যাটফর্মে Cargo দিয়ে ইনস্টল করুন। এসব প্ল্যাটফর্মে Rust toolchain উপলভ্য থাকলে PyPI প্যাকেজটি সোর্স থেকেও তৈরি করা যায়।

আপনি যদি সোর্স চেকআউট থেকে কাজ করেন, Cargo-এর মাধ্যমে কমান্ড চালান:

cargo run -- <command>

একটি রিপোজিটরি শুরু করুন

রিপোজিটরির রুট থেকে seiso চালান। প্রথমে একটি প্রাথমিক কনফিগারেশন তৈরি করতে বলুন:

seiso init

এটি রিপোজিটরির রুটে একটি seiso.toml ফাইল লিখবে। তৈরি হওয়া কনফিগারেশনে প্রস্তাবিত বর্জন এবং ডকুমেন্ট-ধরনের ম্যাপিং থাকে। ফলাফলের ওপর নির্ভর করার আগে এসব প্রস্তাব পর্যালোচনা করুন, কারণ প্রাথমিক ম্যাপিং আপনার রিপোজিটরির জন্য একটি সূচনাবিন্দু, প্রকল্পের সিদ্ধান্তের বিকল্প নয়।

প্রথম পরীক্ষা চালান

তৈরি হওয়া কনফিগারেশন পর্যালোচনা করার পর রিপোজিটরি পরীক্ষা করুন:

seiso check

ডিফল্টভাবে seiso check কেবল স্থিতিশীল নিয়ম চালায়। এসব নিয়ম seiso-এর প্রচলনের মানদণ্ড পূরণ করেছে এবং প্রকল্পের জন্য নির্ভরযোগ্য ভিত্তি দেওয়ার উদ্দেশ্যে তৈরি।

ডায়াগনস্টিক বার্তায় সমস্যাটি কোথায় ঘটেছে এবং কীভাবে ঠিক করতে হবে তা জানানো হয়। তাই অনেক ফলাফল কমান্ডের আউটপুট থেকেই সরাসরি সংশোধন করা যায়। কোনো ফলাফলের জন্য মানুষের বিচার প্রয়োজন হলে, যেমন দুটি পৃষ্ঠার কোনটি কোনো তথ্যের মূল স্থান হবে তা নির্ধারণ করতে হলে, ডায়াগনস্টিকে যে সিদ্ধান্ত নিতে হবে তা উল্লেখ করা হয়।

নিয়ম ও ডকুমেন্টের কাঠামো অন্বেষণ করুন

seiso কী কী পরীক্ষা করতে পারে তা বুঝতে নিয়ম-সংক্রান্ত কমান্ড ব্যবহার করুন:

seiso rule --all
seiso rule <CODE>

seiso rule --all প্রতিটি নিয়মের তালিকা এবং তার অবস্থা দেখায়। কোনো নির্দিষ্ট নিয়মের উদাহরণসহ বিবরণ দেখতে seiso rule <CODE> ব্যবহার করুন।

নিয়ম না চালিয়ে seiso-এর ডকুমেন্ট মডেল পরিদর্শন করতে ব্যবহার করুন:

seiso parse

টুলটি কোনো ডকুমেন্ট কীভাবে ব্যাখ্যা করে তা শেখার সময় বা কোনো পরীক্ষা কেন নির্দিষ্ট ফল দিয়েছে তা অনুসন্ধানের সময় এটি উপযোগী।

প্রিভিউ নিয়ম সতর্কতার সঙ্গে ব্যবহার করুন

যেসব নিয়ম এখনও প্রচলনের মানদণ্ড পূরণ করেনি, সেগুলো প্রিভিউ হিসেবে উপলভ্য। প্রিভিউ নিয়মগুলো পরীক্ষামূলক এবং ভুল ইতিবাচক ফল দিতে পারে, তাই সাধারণ পরীক্ষায় এগুলো সক্রিয় থাকে না।

--preview অপশন দিয়ে স্থানীয়ভাবে এগুলো চেষ্টা করুন:

seiso check --preview

প্রিভিউ নিয়ম আগে থেকেই সম্ভাব্য ডকুমেন্টেশন সমস্যা খুঁজে পেতে কার্যকর, তবে স্থিতিশীল না হওয়া পর্যন্ত README এগুলোকে CI গেটের বাইরে রাখার পরামর্শ দেয়। ব্যবহারিক কর্মপ্রবাহ হলো বাধ্যতামূলক পরীক্ষার জন্য স্থিতিশীল নিয়ম এবং ঐচ্ছিক স্থানীয় পর্যালোচনার জন্য প্রিভিউ নিয়ম ব্যবহার করা।

ডকুমেন্টেশন কর্মপ্রবাহে seiso গ্রহণ করুন

1. Cargo, uv, pipx অথবা npm ব্যবহার করে seiso ইনস্টল করুন।
2. রিপোজিটরির রুট থেকে seiso init চালান।
3. seiso.toml-এ প্রস্তাবিত বর্জন এবং ধরন-ম্যাপিং পর্যালোচনা করুন।
4. seiso check চালিয়ে দেখানো ফলাফলগুলো সমাধান করুন।
5. কোনো ডায়াগনস্টিক বুঝতে হলে seiso rule --all এবং পৃথক নিয়মের ব্যাখ্যা ব্যবহার করুন।
6. স্থানীয়ভাবে seiso check --preview দিয়ে পরীক্ষা করুন, তবে CI গেট হিসেবে প্রিভিউ ফলাফল ব্যবহার করা এড়িয়ে চলুন।

বড় কর্মপ্রবাহের জন্য seiso-এর ডকুমেন্টেশনে কনফিগারেশন, নিয়ম নির্বাচন এবং আউটপুট ফরম্যাট এবং Claude Code hooks, pre-commit এবং CI ইন্টিগ্রেশন সম্পর্কে নির্দেশনা রয়েছে।

উন্নত নির্দেশনা

তথ্যের নির্ভরযোগ্য মূল স্থান বজায় রাখুন

seiso যখন ডুপ্লিকেট বা ভুল স্থানে থাকা তথ্য শনাক্ত করে, তখন ঠিক করুন কোন নথিতে তথ্যটির মালিকানা থাকবে। সেখানে প্রামাণ্য ব্যাখ্যাটি রাখুন এবং সংশ্লিষ্ট পৃষ্ঠাগুলো থেকে সেটির লিংক দিন। এতে আপডেট করা আরও নিরাপদ হয় এবং পাঠক ও এজেন্ট উভয়ের জন্যই সত্যের একটি সুস্পষ্ট উৎস থাকে।

উদ্দেশ্যের সঙ্গে নথির ধরন মিলিয়ে নিন

ধাপে ধাপে করণীয় নির্দেশনার জন্য howto, স্থায়ী তথ্যের জন্য reference, এবং কোনো নকশাগত সিদ্ধান্তের পেছনের যুক্তির জন্য adr ব্যবহার করুন। এই উদ্দেশ্যগুলো আলাদা রাখলে একটি পৃষ্ঠা নির্দেশনা, রেফারেন্স তথ্য এবং ঐতিহাসিক সিদ্ধান্ত গ্রহণের মিশ্রণে পরিণত হয় না।

যুক্তিসংগত ব্যতিক্রম নথিবদ্ধ করুন

কিছু রিপোজিটরি-সংক্রান্ত সিদ্ধান্তে যান্ত্রিক নিয়মের বদলে বিচারবোধ প্রয়োজন। কোনো ব্যতিক্রম রাখলে তার কারণ নথিবদ্ধ করুন। seiso ব্যাখ্যাহীন ব্যতিক্রমকে নথিপত্রের সমস্যা হিসেবে বিবেচনা করে, কারণ ভবিষ্যৎ অবদানকারী ও এজেন্টরা বুঝতে পারে না সেটি ইচ্ছাকৃত ছিল কি না।

নিয়ম অস্পষ্ট হলে কনভেনশন দেখুন

seiso কনভেনশন প্রতিটি নথির ধরনের চুক্তি এবং একটি ডায়াগনস্টিক যে প্রমাণের দাবি করতে পারে তা নির্ধারণ করে। প্রত্যাশিত কাঠামো বুঝতে বা কোনো শনাক্ত সমস্যার সমাধান কীভাবে করবেন তা ঠিক করতে seiso rule <CODE>-এর আউটপুটের পাশাপাশি এটি ব্যবহার করুন।

উপসংহার

seiso প্রকল্পের নথিপত্রে একটি অভিন্ন কাঠামো এবং লক্ষ্যভিত্তিক যাচাই সরঞ্জাম প্রদান করে। এটি ইনস্টল করুন, seiso.toml তৈরি ও পর্যালোচনা করুন, স্থিতিশীল পরীক্ষা চালান, এবং নথিপত্রকে মানুষ ও কোডিং এজেন্ট উভয়ের কাছে আরও নির্ভরযোগ্য করে তুলতে নিয়মের ব্যাখ্যা ব্যবহার করুন। প্রিভিউ নিয়মগুলো অনুমোদিত না হওয়া পর্যন্ত পরীক্ষামূলক হিসেবে বিবেচনা করুন এবং রিপোজিটরিতে মালিকানা ও ব্যতিক্রম-সংক্রান্ত সিদ্ধান্তগুলো স্পষ্টভাবে নথিবদ্ধ রাখুন।