ドキュメント整備をDevinに任せたら、4週間分の作業が6時間のレビューで完了した話
はじめに 弊社エスマットでのファームウェア開発において、しばらく悩まされていた課題だった技術ドキュメントの整備を AI エージェントの Devin に任せてみました。 結果として、人手で 4 週間と見積もられた作業が、わずか 6 時間のレビュー作業で完了。合計で 1 万行を超える Markdown ドキュメントが作成され、ファームウェアの理解促進と AI コーディング精度の向上という目標を実現できそうなところまできました。 この記事では、Devin を活用したドキュメント整備の具体的なアプローチと、実際の運用で得られたノウハウを共有します。 背景：散在・陳腐化したファームウェアドキュメントの課題 ドキュメントの現状と課題 弊社製品であるスマートマットのファームウェアは、元々外注先で開発されたものを引き継いで開発を続けていました。外注先から引き継いだ時点で体系的なドキュメントは無かったようで
なぜ MCP なのか
なぜ自分が MCP を追いかけているのかを雑にだらだらと書いて行こうと思います。 乱文です。 オープンなプロトコル追いかけている理由は Model Context Protocol がオープンなプロトコルにしたことです。これが ChatGPT Plugins とかのクローズドなプロトコルであれば全く追いかけていなかったと思います。 MCP は Anthoropic 以外でも MCP クライアントを実装しさえしていれば、多くの MCP サーバーと接続する事が出来ます。実際 MCP を公開した Anthropic が提供している Claude Desktop や Claude Code だけでなく Cline や Cursor などが MCP クライアントを実装したことにより、MCP サーバーさえ実装してしまえば、様々な環境で利用できる仕組みになっています。 そして VS Code も MCP
AIのためのオンボーディングドキュメントを整備する - inSmartBank
こんにちは、SmartBankでサーバーサイドエンジニアをしているhiroteaです。 ここ最近、CursorをはじめとしたAIを活用したコードエディタの利用が社内で急速に進み、私自身も日常的に「ペアプロ」しています。 特にCursorのAgentモードは、明確な指示を与えることでテストコードまで自律的に生成・実行してくれて非常に便利です。 docs.cursor.com しかし、AIにコード生成をさせていると以下のような悩みに遭遇します。 社内で定めたコーディングルールが守られない 既存の共通クラスやベースクラスをガン無視して独自に実装し直してくる AIあるあるですよね。 例えば、既に認証やエラー処理を包括的に提供しているApi::BaseControllerという共通の親クラスが存在する場合、以下のような実装をすることが望ましいです。 class AratanaController <
情報の見つけやすさを追求する - 社内ドキュメンテーションの階層整理術 - KAKEHASHI Tech Blog
カケハシのプラットフォームチームでソフトウェアエンジニアをしているすてにゃん (id:stefafafan) です。今回はチームに配属されて数ヶ月の私が、いかにして社内ドキュメンテーションの階層構造を整理し、情報の検索性を向上させたかについてお話します。 はじめに この記事の想定読者 課題意識 メンバーへの共有と相談 社外事例の調査 esa の階層整理 第 1・第 2 階層の整理 ストック情報とフロー情報を意識した階層の整理 esa の機能をフル活用する 効果や今後について はじめに カケハシでは全社的にドキュメンテーションツールとして esa - 自律的なチームのための情報共有サービス を利用しています。それぞれのチームやプロダクトごとに階層を切ってドキュメントを書いています。 プラットフォームチームでは認証基盤などの社内プラットフォームシステムを開発しているため、自チームが運用する各種
網羅的なPRDやDesign Docを書かなくなった - kosui
2024/06/12 16:16 結論を追記 2024/06/12 20:29 より記事の内容を分かりやすく理解頂くため、タイトルを「PRDやDesign Docを書かなくなった」から変更 2024/06/13 20:39 結論にフロー情報・ストック情報に関する意見を追記 結論 この記事では、「様々な観点を考慮して網羅的にドキュメントを書いて、それを関係者にレビューしてもらう」のではなく、関係者と同期的に対話しながら、観点や選択肢やそのトレードオフを洗い出すことで、少ない手数でより良い答えが見つけられると主張する。 ただし、対話のために必要なドキュメントは事前に書いておくべきだし、対話した結果はドキュメントに残すことが望ましい。そして、そのドキュメントのフォーマットはPRDやDesign Doc以外でも良い。例えば、ADRはアーキテクチャに関する議論の過程と結果を述べる上で必要十分なフォー
ADR を1年間書いてみた感想 - 一休.com Developers Blog
宿泊開発チームでエンジニアをしている @kosuke1012 です。チームで ADR を書き始めて1年くらい経ったので、その感想を書いてみたいと思います。 この記事は 一休.comのカレンダー | Advent Calendar 2023 - Qiita の13日目の記事です。 ADRとは アーキテクチャ・ディシジョン・レコードの略で、アーキテクチャに関する意思決定を軽量なテキストドキュメントで記録していくものです。 出典はこちらで、 Documenting Architecture Decisions わかりやすい和訳は以下の記事が、 アーキテクチャ決定レコードの概要 | Cloud アーキテクチャ センター | Google Cloud アーキテクチャ・デシジョン・レコードの勧め | 豆蔵デベロッパーサイト アーキテクチャの「なぜ？」を記録する！ADRってなんぞや？ #設計 -
Deno 1.38: HTML doc generator and HMR
If you don’t yet have Deno installed, you can install it with one of the following commands, or many other ways. MacOS / Linux Install curl -fsSL https://deno.land/x/install/install.sh | shWindows Install irm https://deno.land/install.ps1 | iex Here’s an overview of what’s new in Deno 1.38. deno doc improvements: The new deno doc --html command generates a static site with documentation for your p
プログラマーに贈る、わかりやすい文章を書くための技法 - LIVESENSE ENGINEER BLOG
これは Livesense Advent Calendar 2022 DAY 8 の記事です。 転職ドラフトでエンジニアをしている verdy_266 です。 僕の2022年を振り返ると、採用広報チームでの活動を無視することはできません。転職ドラフトの開発を行う傍ら、昨年末に採用広報チームにジョインし、記事の執筆や校正に多くの時間を割いてきました。 今まで記事を投稿したことがなかったこちらのブログにも共作含め5記事を投稿し、11月には Software Design への寄稿の機会をいただくこともできました。文章を書くことが思った以上に好きなんだなと発見があった年でもありました。 made.livesense.co.jp made.livesense.co.jp made.livesense.co.jp made.livesense.co.jp made.livesense.co.jp 弊
技術文書の書き方
howto-tech-docs.md 技術文書の書き方 このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。
Announcing Docusaurus 2.0 | Docusaurus
Today we are extremely happy to finally announce Docusaurus 2.0! 🥳️ At Meta Open Source, we believe Docusaurus will help you build the best documentation websites with minimal effort, letting you focus on what really matters: writing the content. After 4 years of work, 75 alphas and 22 betas, the next generation of Docusaurus is ready for prime time. From now on, we now plan to respect Semantic V
Diagram as Code
Diagram as Code6 different ways to turn code into beautiful architecture diagrams
ドキュメントに固執せよ - gfnweb
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
Notionでのドキュメント管理の何がつらいか - パルカワ2
Notionでドキュメントを書いてる。ドキュメントは書く、共有する、読むなどユーザーそれぞれ色々なシナリオがあり、そのシナリオそれぞれでつらみがある。 Notionに限らずすべてのサービスは使っていればつらいところはあると思っていて、つらいとはいえNotionから別のドキュメント管理サービスに乗り換えたいという気持ちは全くなく何がつらいのか考えNotionでなにか出来ることはないか考えたり、つらみを共有することで知見を得たい。 検索がつらい フロー型とストック型の情報が入り乱れる 検索をする時はストック型の情報を探すことが多い。例えば、リリース作業手順ドキュメントを探したいときに「リリース 作業 手順」で検索するけど日報や議事録などは検索から除外したい。 Notionの検索には、FilterでPageの指定が出来るのでそれを駆使するしかない。Pageの指定をした場合、Pageの配下は検索対
社内のドキュメンテーションの取り組みと、Kitenのご紹介 - Pepabo Tech Portal
はじめに 技術部の @june29 と申します。最近の趣味は「お散歩」で、よく晴れた休日には妻といっしょに2時間くらい歩き回ったりしています。この記事では、わたしが2020年から力を入れて取り組んでいる社内におけるドキュメンテーションの活動の一部を紹介したいと思います。 問題意識 もともと、ペパボで働く人々には「書く」という行為が定着しています。現在利用中のサービスを見渡してみると、GitHub、Slack、Google Docs、Scrapbox、Notionなどがあり、常に積極的な読み書きが行われています。 しかし、ドキュメンテーションという観点から見て、すべてが理想的にうまくいっているとは言えない状況であるとも思っていました。具体的には、下記のような課題があると感じていました。 書く場所が何種類もあり、どこになにが書かれているかがわかりにくい 場所ごとにアクセス制限が行われており、ど
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
FFmpeg By Example
Markwhen
非同期開発体制を支えるドキュメント文化 / YAPC::Hiroshima 2024
Typst: Compose papers faster
テクニカルライティングの基本 2023年版
IT英語スタイルガイド | IT英語スタイルガイド
